IPC API (Preload Bridge)

packages/desktop/src/preload/index.ts exposes a typed CosmoDesktopAPI to the renderer via Electron's contextBridge:

contextBridge.exposeInMainWorld('cosmoDesktop', api)

The renderer accesses it as window.cosmoDesktop.

All methods return Promises (or void for event subscriptions that return an unsubscribe function).

`window.cosmoDesktop.window`

Window control methods for the custom frameless titlebar.

Method	Returns	Description
`minimize()`	`void`	Minimise the window
`maximize()`	`void`	Toggle maximised state
`close()`	`void`	Close the window
`isMaximized()`	`Promise<boolean>`	Current maximised state
`onMaximizedChanged(cb)`	Unsubscribe fn	Listen for resize events

`window.cosmoDesktop.auth`

Method	Returns	Description
`get()`	`Promise<StoredAuth \| null>`	Load stored auth
`login()`	`Promise<void>`	Open web sign-in in browser
`logout()`	`Promise<void>`	Wipe data and relaunch
`onChanged(cb)`	Unsubscribe fn	Listen for `auth:changed`

StoredAuth fields: token, userId, orgId, userName, userEmail, orgName, orgSlug, role, plan?, onboardingCompleted?, welcomeSeen?.

`window.cosmoDesktop.onboarding`

Method	Returns	Description
`getUserProfile(userId)`	`Promise<unknown>`	Load user profile
`saveUserProfile(userId, data)`	`Promise<unknown>`	Save + cloud push. A truthy `completed` also records the server-side onboarding flag, and the response then carries `serverAcknowledged: boolean` — `false` if that server write failed. The local copy is wiped by logout, so an unacknowledged write means the user is onboarded again next sign-in; callers must surface it rather than treat the resolved promise as success
`getState()`	`Promise<{ onboardingCompleted, welcomeSeen } \| null>`	Authoritative first-run popup state for the signed-in user + org; `null` when signed out
`markWelcomeSeen()`	`Promise<boolean>`	Record the welcome-modal dismissal server-side; `false` if the write failed
`getOrgStatus(orgId)`	`Promise<unknown>`	Load org onboarding
`saveOrg(orgId, data)`	`Promise<unknown>`	Save org data + cloud push
`reset(orgId, userId)`	`Promise<void>`	Wipe all onboarding data
`saveAsset(orgId, fileName, buffer, contentType)`	`Promise<unknown>`	Store brand asset
`resolveAssetUrl(ref)`	`Promise<string>`	Resolve `asset://` to `file://` URL
`seedOnboarding(data)`	`Promise<{ seeded: boolean }>`	Seed sample org data
`getSampleTasks(orgId)`	`Promise<unknown[]>`	Get onboarding sample tasks

seedOnboarding takes { companyName?: string; useCase?: string }, not an orgId string.

`window.cosmoDesktop.chat`

Method	Returns	Description
`listSessions()`	`Promise<SessionInfo[]>`	All chat sessions
`createSession(opts?)`	`Promise<SessionInfo>`	Create a new session
`getMessages(sessionId)`	`Promise<DisplayMessage[]>`	Messages for a session
`deleteSession(sessionId)`	`Promise<void>`	Delete session + history
`renameSession(sessionId, title)`	`Promise<{ id, title }>`	User-initiated rename; rejects on failure (network/server) rather than silently reverting
`sendMessage(sessionId, content, context?, model?)`	`void`	Start streaming (events via `onEvent`)
`stop(sessionId)`	`void`	Abort in-flight stream
`getAvailableModels()`	`Promise<ModelInfo[]>`	Models list from server
`confirmTool(confirmId, decision)`	`void`	Resolve a pending tool confirmation — `decision` is `'deny'`, `'allow_once'` or `'always_allow'`; anything else is treated as `'deny'`
`extractOnboarding(sessionId)`	`Promise<unknown>`	Extract memory from onboarding session
`onEvent(cb)`	Unsubscribe fn	Listen for `chat:event`

SessionInfo fields: id, title, createdAt, lastUsedAt, messageCount, hidden?, workspaceId?.

ModelInfo fields: id, displayName, provider, tier, contextWindow.

createSession options:

{
  systemPrompt?: string;
  title?: string;
  userId?: string;
  orgId?: string;
  hidden?: boolean;
  onboarding?: boolean;
}

`window.cosmoDesktop.connectors`

Method	Returns	Description
`getAvailable()`	`Promise<ConnectorType[]>`	Provider catalog from server
`list(token, orgId)`	`Promise<ConnectorInfo[]>`	Installed instances
`add(token, orgId, serverId, label)`	`Promise<ConnectorInfo>`	Start auth flow + create instance
`remove(token, orgId, instanceId)`	`Promise<void>`	Delete instance + tokens

`window.cosmoDesktop.updates`

Method	Returns	Description
`getStatus()`	`Promise<UpdateStatus>`	Current update state
`check()`	`Promise<UpdateStatus>`	Trigger immediate check
`download()`	`Promise<void>`	Start download
`install()`	`void`	Quit and install
`onStatus(cb)`	Unsubscribe fn	Listen for `updates:status` events

`window.cosmoDesktop.tasks`

The tasks namespace exposes only an event listener — there is no list method here. Fetching tasks goes through the server API directly.

Method	Returns	Description
`onChanged(cb)`	Unsubscribe fn	Listen for `tasks:changed` events

`window.cosmoDesktop.workspaces`

Method	Returns	Description
`list(orgId)`	`Promise<WorkspaceInfo[]>`	All user workspaces
`get(orgId, workspaceId)`	`Promise<WorkspaceInfo \| null>`	Single workspace
`create(orgId, name, teamId?, description?)`	`Promise<WorkspaceInfo>`	Create a new workspace under the given team
`update(orgId, workspaceId, name?, description?)`	`Promise<WorkspaceInfo>`	Rename or update description
`delete(orgId, workspaceId)`	`Promise<void>`	Delete workspace + local HTML artifacts
`onChanged(cb)`	Unsubscribe fn	Listen for workspace mutations

`window.cosmoDesktop.teams`

Method	Returns	Description
`list(orgId)`	`Promise<Team[]>`	All user teams
`get(orgId, teamId)`	`Promise<Record<string, unknown> \| null>`	Single team
`listMembers(orgId, teamId)`	`Promise<Record<string, unknown>[]>`	Team members
`onChanged(cb)`	Unsubscribe fn	Listen for team mutations

`window.cosmoDesktop.artifacts`

Method	Returns	Description
`list(orgId, workspaceId)`	`Promise<unknown[]>`	Artifacts in workspace
`get(orgId, artifactId)`	`Promise<unknown>`	Full artifact with HTML
`exportPdf(html, title, mimeType, width?, height?)`	`Promise<{ data: Uint8Array; filename: string }>`	Renders already-fetched `text/html` artifact content to PDF; rejects for any other mimeType. Takes content directly rather than an id, so the caller's own read (via `get`/`getShared`) isn't repeated. `width`/`height`, when supplied, size the hidden export window to match the caller's actual on-screen iframe (falls back to a Hub-panel-like default otherwise) — the export also inlines Google Fonts/Chart.js, applies a default `@page` margin, and runs a print-safety pass (page-break protection, scroll-reveal-animation settling, background fallback) before capture
`softDelete(orgId, artifactId, workspaceId?)`	`Promise<{ deleted: boolean; workspaceId?: string; deletedAt?: string }>`	Soft-delete — moves to Trash; optional `workspaceId` skips full-org scan
`restore(orgId, artifactId, workspaceId?)`	`Promise<{ restored: boolean; workspaceId?: string }>`	Restore from Trash; optional `workspaceId` skips full-org scan
`purge(orgId, artifactId, workspaceId?)`	`Promise<{ deleted: boolean; workspaceId?: string }>`	Permanently delete a trashed artifact (no-op on a live one); optional `workspaceId` skips full-org scan
`listTrashed(orgId)`	`Promise<unknown[]>`	All soft-deleted artifacts across every workspace in the org
`onChanged(cb)`	Unsubscribe fn	Listen for artifact mutations
`onCreated(cb)`	Unsubscribe fn	Listen for new artifacts created by AI

`window.cosmoDesktop.billing`

Method	Returns	Description
`openManage()`	`void`	Open web billing page
`getUsage()`	`Promise<UsageSummary \| null>`	User token usage today
`getSubscription()`	`Promise<SubscriptionDetails \| null>`	Subscription info
`openPortal()`	`Promise<void>`	Open Stripe portal in browser

`window.cosmoDesktop.feedback`

Method	Returns	Description
`onCapture(cb)`	Unsubscribe fn	Receive PostHog survey data from AI

Utility

Property / Method	Type	Description
`platform`	`string`	`darwin` / `win32` / `linux` (direct property, not async)
`getAppVersion()`	`Promise<string>`	Electron app version
`openExternal(url)`	`Promise<void>`	Open URL in system browser
`openWebPage(path)`	`Promise<void>`	Open Cosmo web URL

IPC API (Preload Bridge)

On this page