Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import type { ApplyReport } from './agent-registry/apply.ts';
import type { HandoffHostPlatform } from './agent-registry/schema.ts';
import type { HostSnapshot } from './agent-registry/snapshot.ts';
import type { ConfigValidationError } from './config/errors.ts';
import type { ConfigPatch } from './config/schema.ts';
import type { CreateNewBannerKind } from './constants/create-new-banner.ts';
import type { EditorId } from './constants/editors.ts';
import type { OkFolderState } from './constants/folder-state.ts';
import type {
WorktreeInventoryOpenRequest,
WorktreeInventoryOpenResult,
WorktreeInventoryRequest,
WorktreeInventoryResult,
} from './git/worktree-inventory-model.ts';
import type {
WorktreeCreateRequest,
WorktreeCreateResult,
WorktreeListResult,
} from './git/worktree-selector-model.ts';
import type {
TerminalCli,
TerminalLaunchCommand,
WindowsShellFamily,
WindowsShellLaunchFailureReason,
} from './handoff/terminal-launch.ts';
import type { HandoffFailureReason, HandoffScope } from './handoff/types.ts';
import type { LanguagePreference } from './i18n/locales.ts';
import type {
OkBugReportCrashAckResult,
OkBugReportCrashDetectedEvent,
OkBugReportCrashDumpAvailability,
OkBugReportCreateResult,
OkBugReportDeleteResult,
OkBugReportListResult,
OkBugReportScreenshot,
OkBugReportSendMetadata,
OkBugReportSendResult,
OkImageAttachmentContentType,
ReportBundleLevel,
} from './logger-types.ts';
import type { LintPluginId } from './markdown/lint/types.ts';
import type { LocalOpOkInitResponse } from './schemas/api/local-op.ts';
import type {
BranchInfoResponse,
CheckoutResponse,
ShareTargetStatusResponse,
} from './schemas/api/share.ts';
import type { RecentProjectEntry } from './sharing/index.ts';
import type { SkillCostTiers } from './skills-catalog/skill-cost.ts';
import type { TerminalPlacement } from './terminal-layout.ts';
export type { OkFolderState } from './constants/folder-state.ts';
export type { BridgeWorktreeEntry } from './git/worktree-list-parser.ts';
export type { RecentProjectEntry } from './sharing/index.ts';
export type { TerminalPlacement } from './terminal-layout.ts';
export interface OkTerminalRestartTab {
ordinal: number;
customLabel: string | null;
}
export interface OkTerminalRestartSnapshot {
tabs: OkTerminalRestartTab[];
activeOrdinal: number | null;
}
export interface OkTerminalDockState {
terminalVisible: boolean;
agentPanelVisible: boolean;
editorVisible?: boolean;
terminal?: { order: string[]; activeKey: string | null };
terminalSnapshot?: OkTerminalRestartSnapshot;
agents?: { order: string[]; activeKey: string | null };
}
export type OkNoteWindowMainAction =
| {
readonly kind: 'active-input';
readonly text: string;
readonly newTab: boolean;
readonly submit: boolean;
readonly target?: 'agents';
}
| {
readonly kind: 'agent-thread';
readonly agentSource: 'registry' | 'custom';
readonly agentId: string;
readonly prompt: string | null;
readonly docName: string | null;
readonly titleHint: string | null;
}
| {
readonly kind: 'terminal-launch';
readonly prompt: string;
readonly cli: TerminalCli;
readonly stage: boolean;
}
| {
readonly kind: 'reveal-comments';
readonly docName: string;
readonly scope: 'doc' | 'queue';
};
export type OkNoteWindowMainActionResult =
| { readonly ok: true }
| {
readonly ok: false;
readonly reason: 'invalid-action' | 'not-note-window' | 'project-not-open';
};
export type OkTerminalDockStateUpdate =
| {
surface: 'terminal';
order: string[];
activeKey: string | null;
terminalSnapshot: OkTerminalRestartSnapshot;
}
| {
surface: 'agents';
order: string[];
activeKey: string | null;
};
export type OkTerminalDockStateWriteResult =
| { ok: true }
| {
ok: false;
reason: 'invalid-request' | 'no-window-context' | 'persist-failed' | 'ipc-unavailable';
};
export type OkDesktopMode = 'editor' | 'navigator' | 'terminal' | 'note';
export interface OkDesktopConfig {
readonly collabUrl: string;
readonly apiOrigin: string;
readonly projectPath: string;
readonly projectName: string;
readonly mode: OkDesktopMode;
readonly e2eSmoke: boolean;
readonly singleFile: boolean;
readonly initialDoc: string | null;
readonly freshlyCreated: boolean;
readonly startupTraceparent?: string;
readonly ptyAvailable: boolean;
readonly languagePreference?: LanguagePreference;
readonly themePreference?: OkThemeSource;
}
export type OkMenuAction =
| 'new-doc'
| 'new-folder'
| 'new-project'
| 'rename'
| 'delete'
| 'close-active-tab-or-window'
| 'toggle-sidebar'
| 'toggle-source'
| 'save-version'
| 'version-history'
| 'focus-search'
| 'focus-command-palette'
| 'navigate-back'
| 'navigate-forward'
| 'new-from-template'
| 'duplicate'
| 'move-to-trash'
| 'reveal-in-finder'
| 'send-to-ai'
| 'copy-full-path'
| 'copy-relative-path'
| 'toggle-show-hidden-files'
| 'toggle-show-ok-folders'
| 'toggle-show-only-markdown-files'
| 'toggle-show-skills-section'
| 'expand-all-tree'
| 'collapse-all-tree'
| 'toggle-doc-panel'
| 'toggle-terminal'
| 'move-terminal'
| 'toggle-agent-panel'
| 'toggle-editor'
| 'new-terminal'
| 'kill-terminal'
| 'new-worktree'
| 'switch-worktree'
| 'report-bug'
| 'send-feedback';
export interface OkMenuActionOrigin {
readonly launcherBorne: boolean;
}
export interface OkMenuActionDispatch {
readonly action: OkMenuAction;
readonly origin: OkMenuActionOrigin;
}
export type OkUnsubscribe = () => void;
export interface PersistedEditorPane {
id: string;
openTabs: string[];
pinnedTabIds: string[];
activeTabId: string | null;
size: number;
}
export interface ProjectSessionState {
updatedAt: string | null;
panes: PersistedEditorPane[];
focusedPaneId: string;
}
export type OkProjectEntryPoint =
| 'create-new'
| 'create-new-nested-redirect'
| 'pick-existing'
| 'recents'
| 'deep-link'
| 'drag-drop'
| 'share-receive'
| 'worktree';
export interface OkProjectOpenRequest {
path: string;
target: 'new-window';
entryPoint: OkProjectEntryPoint;
requireExactManagedProject?: boolean;
pendingDeepLinkTarget?: {
kind: 'doc' | 'folder';
path: string;
repositoryPath?: string;
contentRootDepth?: number;
};
pendingBranch?: string | null;
pendingShareBranchSwitch?: {
share: OkSharePayloadFields;
projectPath: string;
currentBranch: string | null;
};
}
export type OkCheckTargetExistsResult = 'exists' | 'missing' | 'unreadable';
export interface OkHeadBranchInfo {
readonly currentBranch: string | null;
readonly headSha: string | null;
readonly detached: boolean;
}
export interface OkUpdateDownloadedInfo {
readonly version: string | null;
}
export interface OkUpdateRelaunchingInfo {
readonly version: string;
}
export interface OkUpdateFetchingLatestInfo {
readonly version: string;
}
export interface OkUpdateRelaunchFailedInfo {
readonly version: string;
readonly message?: string;
readonly downloadUrl?: string;
readonly dismissPending?: boolean;
readonly reason?: 'no-longer-pending';
}
export interface OkWhatsNewInfo {
readonly version: string;
readonly releaseUrl: string;
}
export interface OkUpdateStuckHintInfo {
readonly downloadUrl: string;
}
export interface OkUpdateManualCheckInfo {
readonly phase: 'started' | 'settled';
}
export interface OkAboutInfo {
readonly productName: string;
readonly version: string;
readonly releasesUrl: string;
readonly releaseNotesUrl: string;
readonly updateChecks: 'available' | 'unavailable';
}
export type ShareTarget =
| { readonly kind: 'doc'; readonly docPath: string }
| { readonly kind: 'folder'; readonly folderPath: string };
export interface OkSharePayloadFields {
readonly host: string;
readonly owner: string;
readonly repo: string;
readonly branch: string;
readonly sharedUrl: string;
readonly repositoryTarget: ShareTarget;
readonly contentRootDepth: number | null;
readonly target: ShareTarget;
}
export type OkShareReceivedPayload =
| { readonly kind: 'unsupported-version' }
| { readonly kind: 'invalid' }
| {
readonly kind: 'project-branch-switch';
readonly share: OkSharePayloadFields;
readonly projectPath: string;
readonly currentBranch: string | null;
}
| {
readonly kind: 'launcher-consent';
readonly share: OkSharePayloadFields;
readonly candidatePath: string;
readonly parentProjectName: string | null;
}
| {
readonly kind: 'launcher-miss';
readonly share: OkSharePayloadFields;
};
export type ShareFolderValidationResult =
| { readonly kind: 'ok'; readonly gitRemoteUrl: string }
| { readonly kind: 'not-git' }
| { readonly kind: 'no-origin' }
| { readonly kind: 'wrong-repo'; readonly actualOwner: string; readonly actualRepo: string }
| { readonly kind: 'wrong-host'; readonly actualHost: string }
| { readonly kind: 'non-github' }
| { readonly kind: 'symlink-escape' };
export type OkUpdateChannel = 'latest' | 'beta';
export type OkUpdateMode = 'auto' | 'off';
export type OkThemeSource = 'system' | 'light' | 'dark';
export interface OkUserConfigSnapshot {
readonly text: string;
}
export type OkUserConfigPatchResult =
| { readonly ok: true; readonly text: string }
| { readonly ok: false; readonly error: ConfigValidationError };
export interface OkUserConfigBridge {
read(): Promise<OkUserConfigSnapshot>;
patch(patch: ConfigPatch): Promise<OkUserConfigPatchResult>;
onChanged(cb: (snapshot: OkUserConfigSnapshot) => void): OkUnsubscribe;
}
export interface OkChromeColors {
bg: string;
symbol: string;
}
export interface OkStateSnapshot {
readonly channel: OkUpdateChannel;
readonly schemaIncompatibility: {
readonly currentBuild: string;
readonly persistedSchemaVersion: number;
readonly maxSupported: number;
} | null;
readonly about?: OkAboutInfo;
readonly updateMode?: OkUpdateMode;
}
export type OkMcpWiringEditorId = EditorId;
export interface OkMcpWiringShowPayload {
readonly origin: 'first-run' | 'reconfigure';
readonly detectedEditors: readonly {
readonly id: OkMcpWiringEditorId;
readonly label: string;
readonly detected: boolean;
readonly willReplace: boolean;
readonly configPath: string | null;
readonly entryLocator: string;
}[];
readonly pathInstall: {
readonly shellDetected: boolean;
readonly rcFilesToTouch: readonly string[];
readonly alreadyInstalled: boolean;
};
readonly globalSkills: readonly {
readonly id: string;
readonly name: string;
readonly paths: readonly string[];
}[];
}
export interface OkMcpWiringConfirmRequest {
readonly editorIds: readonly OkMcpWiringEditorId[];
readonly pathInstall?: boolean;
readonly skills?: readonly string[];
}
export type OkMcpWiringResult = { ok: true } | { ok: false; error: string };
export type OkIntegrationsEditorState = 'installed' | 'not-installed' | 'foreign' | 'unmanageable';
export interface OkIntegrationsStatus {
readonly available: boolean;
readonly editors: readonly {
readonly id: OkMcpWiringEditorId;
readonly label: string;
readonly detected: boolean;
readonly state: OkIntegrationsEditorState;
readonly configPath: string | null;
readonly entryLocator: string;
}[];
readonly path: {
readonly shellDetected: boolean;
readonly rcFilesToTouch: readonly string[];
readonly installed: boolean;
};
readonly skills: readonly {
readonly id: string;
readonly name: string;
readonly description: string;
readonly installed: boolean;
readonly onboarding: boolean;
readonly paths: readonly string[];
readonly size?: SkillCostTiers;
readonly sourceDir: string;
readonly resolvedHosts: readonly {
readonly editor: string;
readonly skillsRoot: string;
readonly custom: boolean;
}[];
}[];
readonly detectedEditorIds: readonly OkMcpWiringEditorId[];
}
export interface OkIntegrationsSetRequest {
readonly component:
| { readonly kind: 'editor'; readonly id: OkMcpWiringEditorId }
| { readonly kind: 'path' }
| { readonly kind: 'skill'; readonly id: string };
readonly enabled: boolean;
}
export type OkIntegrationsSetResult =
| { readonly ok: true; readonly status: OkIntegrationsStatus }
| { readonly ok: false; readonly error: string; readonly status: OkIntegrationsStatus };
export interface OkProjectIntegrationsStatus {
readonly available: boolean;
readonly hasProject: boolean;
readonly projectDir: string | null;
readonly editors: readonly {
readonly id: OkMcpWiringEditorId;
readonly label: string;
readonly detected: boolean;
readonly state: OkIntegrationsEditorState;
readonly configPath: string;
readonly entryLocator: string;
}[];
readonly skill: {
readonly installed: boolean;
readonly paths: readonly string[];
readonly description: string;
readonly hosts: readonly string[];
readonly size?: SkillCostTiers;
readonly sourceDir?: string;
} | null;
}
export interface OkProjectIntegrationsSetRequest {
readonly component:
| { readonly kind: 'editor'; readonly id: OkMcpWiringEditorId }
| { readonly kind: 'skill' };
readonly enabled: boolean;
}
export type OkProjectIntegrationsSetResult =
| { readonly ok: true; readonly status: OkProjectIntegrationsStatus }
| { readonly ok: false; readonly error: string; readonly status: OkProjectIntegrationsStatus };
export interface OkAgentIntegrationsIntent {
readonly satisfierId: string;
readonly desired: 'present' | 'absent';
}
export interface OkAgentIntegrationsApplyRequest {
readonly intents: readonly OkAgentIntegrationsIntent[];
}
export type OkAgentIntegrationsApplyResult =
| {
readonly ok: true;
readonly report: ApplyReport;
readonly snapshot: HostSnapshot;
}
| {
readonly ok: false;
readonly error: string;
readonly unavailable?: boolean;
readonly devBuild?: boolean;
readonly report: ApplyReport;
readonly snapshot: HostSnapshot;
};
export type OkOnboardingWarningKind =
| 'home-documents'
| 'home-desktop'
| 'home-downloads'
| 'volumes-mount';
export type OkOnboardingGitState = 'present' | 'absent' | 'shell-only';
export interface OkOnboardingShowPayload {
readonly pickedPath: string;
readonly projectDir: string;
readonly defaultContentDir: string;
readonly gitState: OkOnboardingGitState;
readonly gitRootPromoted: boolean;
readonly warnings: readonly { readonly kind: OkOnboardingWarningKind }[];
}
export interface OkDeepLinkPayload {
doc: string;
kind: 'doc' | 'folder';
branch?: string | null;
multiCandidate?: boolean;
targetMissing?: boolean;
repositoryPath?: string;
contentRootDepth?: number;
}
export type OkOnboardingToastPayload =
| { readonly kind: 'ancestor-promote'; readonly ancestorPath: string }
| { readonly kind: 'git-root-promote'; readonly gitRoot: string; readonly pickedPath: string }
| {
readonly kind: 'startup-reclaim';
readonly mcp:
| { readonly status: 'none' }
| { readonly status: 'repaired'; readonly editors: readonly string[] }
| {
readonly status: 'failed';
readonly failures: readonly { readonly editor: string; readonly reason?: string }[];
readonly repaired?: readonly string[];
};
readonly path:
| { readonly status: 'none' }
| { readonly status: 'installed'; readonly summary: string }
| { readonly status: 'failed'; readonly summary: string };
}
| {
readonly kind: 'sharing-refused-tracked';
readonly tracked: readonly string[];
readonly remediation: string;
}
| { readonly kind: 'sharing-no-git'; readonly requestedMode: 'local-only' };
export interface OkOnboardingConfirmRequest {
readonly initGit: boolean;
readonly contentDir: string;
readonly additionalIgnores: string;
readonly editorIds: readonly OkMcpWiringEditorId[];
readonly connectEditors: boolean;
readonly sharing: 'shared' | 'local-only';
}
export type OkOnboardingResult = { ok: true } | { ok: false; error: string };
export interface OkOnboardingProbeContentRequest {
readonly contentDir: string;
}
export type OkOnboardingProbeContentResult =
| {
readonly ok: true;
readonly count: number;
readonly sample: readonly string[];
readonly truncated: boolean;
}
| { readonly ok: false; readonly error: string };
export interface OkKeyringSmokeResult {
ok: boolean;
backend?: 'keyring' | 'file';
error?: string;
durationMs?: number;
timestamp: string;
}
export interface OkScaffoldFileEntry {
path: string;
kind: 'folder' | 'file';
contentPreview?: string;
}
export interface OkScaffoldSkipEntry {
path: string;
reason: 'already-exists' | 'user-content' | 'glob-collision';
}
export interface OkScaffoldPlan {
created: OkScaffoldFileEntry[];
skipped: OkScaffoldSkipEntry[];
warnings: string[];
packSkills?: { name: string; pending: boolean; conflict?: boolean }[];
requiredPlugins?: { id: LintPluginId; pending: boolean }[];
}
export interface OkScaffoldApplyError {
path: string;
error: string;
}
export interface OkScaffoldApplyResult {
applied: number;
errors: OkScaffoldApplyError[];
durationMs: number;
packSkillsInstalled: string[];
pluginsEnabled: LintPluginId[];
packSkillConflicts: { name: string; hosts?: string[] }[];
}
export interface OkSeedError {
kind: 'no-project' | 'prerequisite-missing' | 'invalid-root' | 'internal';
message: string;
}
export type OkPackId =
| 'knowledge-base'
| 'software-lifecycle'
| 'codebase-wiki'
| 'plain-notes'
| 'worldbuilding'
| 'writing-pipeline'
| 'entity-vault'
| 'okf';
export interface OkSeedPlanOptions {
rootDir?: string;
packId?: OkPackId;
preview?: { skillsInstallable: boolean };
}
export interface OkSeedApplyOptions {
packId?: OkPackId;
}
export interface OkSeedPackFolderInfo {
path: string;
summary: string;
}
export interface OkSeedPackEntryCounts {
files: number;
folders: number;
}
export interface OkSeedPackInfo {
id: OkPackId;
name: string;
description: string;
defaultSubfolder?: string;
folders: OkSeedPackFolderInfo[];
entryCounts: OkSeedPackEntryCounts;
}
export interface OkFindEnclosingProjectRootResult {
readonly rootPath: string;
readonly distance: number;
}
export interface OkFindEnclosingGitRootResult {
readonly gitRoot: string;
readonly distance: number;
}
export type OkSeedPlanResult =
| { ok: true; plan: OkScaffoldPlan }
| { ok: false; error: OkSeedError };
export type OkSeedApplyResult =
| { ok: true; result: OkScaffoldApplyResult }
| { ok: false; error: OkSeedError };
export type OkSeedListPacksResult =
| { ok: true; packs: OkSeedPackInfo[] }
| { ok: false; error: { kind: 'internal'; message: string } };
export type OkLocalOpAuthSignoutResponse = { ok: true } | { ok: false; error?: string };
export type OkLocalOpAuthEvent =
| {
type: 'verification';
user_code: string;
verification_uri: string;
expires_in: number;
}
| {
type: 'complete';
host: string;
login: string;
name?: string;
email?: string;
avatarUrl?: string;
}
| { type: 'error'; message: string };
export type OkLocalOpCloneEvent =
| { type: 'progress'; phase: string; pct: number }
| { type: 'complete'; dir: string }
| { type: 'branch-fallback'; branch: string }
| {
type: 'error';
message: string;
code?: 'unsafe-symlinks';
refusedSymlinkPaths?: string[];
};
export interface OkLocalOpStream<E> {
readonly events: AsyncIterable<E>;
cancel(): void;
}
export type OkLocalOpAuthStatusResponse =
| {
authenticated: true;
host: string;
login: string;
tier?: 'A' | 'B' | 'C';
name?: string;
email?: string;
ghAvailable?: boolean;
}
| { authenticated: false; host: string; error?: string; ghAvailable?: boolean };
export interface OkLocalOpRepoEntry {
full_name: string;
clone_url: string;
private: boolean;
}
export type OkLocalOpAuthReposResponse =
| { ok: true; host: string; repos: OkLocalOpRepoEntry[] }
| { ok: false; error: string; authenticated?: false };
export type OkEditorActiveTargetSnapshot =
| { readonly kind: 'doc'; readonly identifier: string }
| { readonly kind: 'folder'; readonly identifier: string }
| { readonly kind: 'asset'; readonly identifier: string }
| { readonly kind: null };
export interface OkEditorViewMenuStateSnapshot {
readonly showHiddenFiles: boolean;
readonly showOkFolders: boolean;
readonly showOnlyMarkdownFiles: boolean;
readonly showSkillsSection: boolean;
readonly canExpandAll: boolean;
readonly canCollapseAll: boolean;
readonly sidebarVisible: boolean;
readonly docPanelVisible?: boolean;
readonly terminalVisible?: boolean;
readonly terminalPlacement?: TerminalPlacement;
readonly terminalLive?: boolean;
readonly agentPanelVisible?: boolean;
readonly editorVisible?: boolean;
readonly canViewInSource?: boolean;
readonly hasEditorSelection?: boolean;
}
export interface OkEditorWideVisibility {
readonly editorVisible?: boolean;
readonly terminalVisible?: boolean;
readonly agentPanelVisible?: boolean;
}
type OkEditorDockVisibilityKey = keyof OkEditorWideVisibility;
type OkEditorOnlyPane<K extends OkEditorDockVisibilityKey> = { readonly [P in K]: boolean } & {
readonly [P in Exclude<OkEditorDockVisibilityKey, K>]?: never;
};
type OkEditorDockVisibilityChange = {
[K in OkEditorDockVisibilityKey]: OkEditorOnlyPane<K> & {
readonly wideIntent: OkEditorOnlyPane<K>;
};
}[OkEditorDockVisibilityKey];
export type OkEditorViewMenuStateChange = Partial<
Omit<OkEditorViewMenuStateSnapshot, OkEditorDockVisibilityKey>
> &
(
| OkEditorDockVisibilityChange
| ({ readonly [K in OkEditorDockVisibilityKey]?: never } & { readonly wideIntent?: never })
);
export type OkMenuDispatchRole =
| 'undo'
| 'redo'
| 'cut'
| 'copy'
| 'paste'
| 'selectAll'
| 'reload'
| 'forceReload'
| 'toggleDevTools'
| 'resetZoom'
| 'zoomIn'
| 'zoomOut'
| 'toggleFullScreen'
| 'minimize'
| 'close'
| 'quit'
| 'about';
export type OkMenuDispatchCommand =
| 'open-navigator'
| 'open-folder-dialog'
| 'clear-recent-projects'
| 'open-settings'
| 'check-for-updates'
| 'reconfigure-mcp-wiring'
| 'open-github'
| 'open-docs'
| 'open-discord'
| 'toggle-spell-check';
export type OkMenuDispatchRequest =
| { readonly kind: 'query' }
| { readonly kind: 'menu-action'; readonly action: OkMenuAction }
| { readonly kind: 'command'; readonly command: OkMenuDispatchCommand }
| { readonly kind: 'open-recent-project'; readonly path: string }
| { readonly kind: 'role'; readonly role: OkMenuDispatchRole }
| { readonly kind: 'spelling-languages-query' }
| { readonly kind: 'spelling-languages-set'; readonly languages: readonly string[] }
| { readonly kind: 'spellcheck-enabled-set'; readonly enabled: boolean };
export type OkSpellingLanguagesSetReason =
| 'invalid-request'
| 'empty-selection'
| 'unsupported-language'
| 'engine-error';
export interface OkSpellingLanguagesState {
readonly available: readonly string[];
readonly selected: readonly string[];
readonly defaults: readonly string[];
}
export type OkSpellingLanguagesQueryResult =
| {
readonly kind: 'spelling-languages-query';
readonly ok: true;
readonly state: OkSpellingLanguagesState;
}
| {
readonly kind: 'spelling-languages-query';
readonly ok: false;
readonly reason: 'engine-error';
};
export type OkSpellingLanguagesSetResult =
| {
readonly kind: 'spelling-languages-set';
readonly ok: true;
readonly state: OkSpellingLanguagesState;
}
| {
readonly kind: 'spelling-languages-set';
readonly ok: false;
readonly reason: OkSpellingLanguagesSetReason;
};
export type OkSpellcheckEnabledSetResult =
| {
readonly kind: 'spellcheck-enabled-set';
readonly ok: true;
readonly enabled: boolean;
readonly saved: boolean;
}
| {
readonly kind: 'spellcheck-enabled-set';
readonly ok: false;
readonly reason: 'engine-error' | 'invalid-request';
};
export type OkSpellingDispatchResult =
| OkSpellingLanguagesQueryResult
| OkSpellingLanguagesSetResult
| OkSpellcheckEnabledSetResult;
export type OkMenuUiDispatchRequest = Exclude<
OkMenuDispatchRequest,
{ readonly kind: OkSpellingDispatchResult['kind'] }
>;
export interface OkMenuRendererSnapshot {
readonly recentProjects: ReadonlyArray<{ readonly path: string; readonly name: string }>;
readonly spellCheckEnabled: boolean;
readonly showDevToolsMenu: boolean;
readonly canCheckForUpdates: boolean;
readonly canReconfigureMcpWiring: boolean;
readonly activeTarget: OkEditorActiveTargetSnapshot;
readonly viewMenuState: OkEditorViewMenuStateSnapshot;
}
export type OkMenuDispatchResult = OkMenuRendererSnapshot | OkSpellingDispatchResult | undefined;
export interface OkBugReportSendInput {
zipPath: string;
metadata: OkBugReportSendMetadata;
includeScreenshot?: boolean;
includeAttachments?: boolean;
traceparent?: string;
}
export interface OkBugReportAttachmentInput {
contentType: OkImageAttachmentContentType;
bytes: Uint8Array;
}
export interface OkAssetUploadRequest {
contentType: OkImageAttachmentContentType;
bytes: Uint8Array;
filename: string;
}
export type OkAssetUploadResult =
| { assetUrl: string }
| { error: 'invalid-request' | 'unconfigured' | 'mint' | 'upload' };
export interface OkSharingStatusResult {
readonly kind: 'status';
readonly mode: 'shared' | 'local-only' | 'no-git';
readonly excluded: readonly string[];
readonly trackedUpstream: readonly string[];
}
export type OkSharingSetModeResult =
| { readonly kind: 'applied'; readonly mode: 'shared' | 'local-only' | 'no-git' }
| {
readonly kind: 'refused-tracked';
readonly tracked: readonly string[];
readonly remediation: string;
}
| {
readonly kind: 'no-exclude';
readonly reason: 'no-git' | 'no-info-dir' | 'malformed-pointer' | 'inaccessible';
};
export type SlidevSource = 'project-local' | 'global';
export type OkSlidesStatusResult =
| { readonly kind: 'status'; readonly available: true; readonly source: SlidevSource }
| { readonly kind: 'status'; readonly available: false };
export type SlidevOpenFailureReason =
| 'not-available'
| 'invalid-path'
| 'spawn-error'
| 'port-error'
| 'exited-early'
| 'cancelled'
| 'load-failed'
| 'renderer-failed'
| 'timeout'
| 'unsupported-server';
export type OkSlidesOpenResult =
| { readonly kind: 'open'; readonly ok: true }
| { readonly kind: 'open'; readonly ok: false; readonly reason: SlidevOpenFailureReason };
export interface OkServerVersionDriftInfo {
readonly relation: 'older' | 'newer';
readonly dimension: 'protocol' | 'runtime';
readonly serverRuntime: string;
readonly appRuntime: string;
}
export interface OkServerRestartedInfo {
readonly appRuntime: string;
}
export interface OkRecentRemovedMissingInfo {
readonly path: string;
readonly projectName: string;
}
export type OkServerRestartFailure =
| { readonly ok: false; readonly reason: 'eperm' | 'other' }
| { readonly ok: false; readonly reason: 'other-channel'; readonly holderChannel: string }
| { readonly ok: false; readonly reason: 'unverified'; readonly sigtermSent: boolean };
export type OkServerRestartOutcome = { readonly ok: true } | OkServerRestartFailure;
export type OkPtyCreateReason = 'no-project' | 'not-consented';
export type OkAssetOpenRefusalReason =
| 'extension-blocked'
| 'not-a-file'
| 'path-escape'
| 'not-found'
| 'resolve-error';
export type OkAssetOpenResult =
| { readonly ok: true }
| { readonly ok: false; readonly reason: OkAssetOpenRefusalReason };
export function assetOpenRefusalRevealsInstead(reason: OkAssetOpenRefusalReason): boolean {
switch (reason) {
case 'extension-blocked':
case 'not-a-file':
return true;
case 'path-escape':
case 'not-found':
case 'resolve-error':
return false;
default: {
const _unknownFromNewerDesktop: never = reason;
return false;
}
}
}
export function assertNeverPtyCreateReason(value: never): never {
throw new Error(`unhandled pty create reason: ${String(value)}`);
}
export type OkPtyCreateResult =
| { readonly ok: true; readonly ptyId: string }
| { readonly ok: false; readonly reason: OkPtyCreateReason };
export interface OkPtyListEntry {
readonly ptyId: string;
readonly customLabel: string | null;
readonly ordinal: number | null;
}
export type OkPtyAdoptReason =
| 'unknown-session'
| 'not-started'
| 'not-consented'
| 'host-unavailable';
export function assertNeverPtyAdoptReason(value: never): never {
throw new Error(`unhandled pty adopt reason: ${String(value)}`);
}
export type OkPtyAdoptResult =
| {
readonly ok: true;
readonly replay: string;
readonly shellFamily?: WindowsShellFamily;
readonly shellNoticeReason?: Extract<TerminalShellNoticeReason, 'unsupported-family'>;
}
| {
readonly ok: false;
readonly reason: OkPtyAdoptReason;
};
export interface OkPtyData {
readonly ptyId: string;
readonly data: string;
}
export type OkPtyExit =
| {
readonly ptyId: string;
readonly neverStarted: true;
readonly error?: string;
readonly hostExited?: true;
readonly launchFailure?: WindowsShellLaunchFailureReason;
}
| {
readonly ptyId: string;
readonly neverStarted?: false;
readonly exitCode: number;
readonly signal: number | null;
readonly error?: string;
readonly hostExited?: true;
};
const TERMINAL_SHELL_NOTICE_REASON_VOCABULARY = [
'config-unreadable',
'invalid-value',
'not-absolute',
'not-found',
'unsupported-family',
] as const;
export type TerminalShellNoticeReason = (typeof TERMINAL_SHELL_NOTICE_REASON_VOCABULARY)[number];
export const TERMINAL_SHELL_NOTICE_REASONS: ReadonlySet<TerminalShellNoticeReason> = new Set(
TERMINAL_SHELL_NOTICE_REASON_VOCABULARY,
);
export function isTerminalShellNoticeReason(value: unknown): value is TerminalShellNoticeReason {
return (
typeof value === 'string' &&
TERMINAL_SHELL_NOTICE_REASONS.has(value as TerminalShellNoticeReason)
);
}
const TERMINAL_SUPPORT_FILE_NOTICE_REASON_VOCABULARY = [
'containment-refused',
'write-failed',
] as const;
export type TerminalSupportFileNoticeReason =
(typeof TERMINAL_SUPPORT_FILE_NOTICE_REASON_VOCABULARY)[number];
export const TERMINAL_SUPPORT_FILE_NOTICE_REASONS: ReadonlySet<TerminalSupportFileNoticeReason> =
new Set(TERMINAL_SUPPORT_FILE_NOTICE_REASON_VOCABULARY);
export function isTerminalSupportFileNoticeReason(
value: unknown,
): value is TerminalSupportFileNoticeReason {
return (
typeof value === 'string' &&
TERMINAL_SUPPORT_FILE_NOTICE_REASONS.has(value as TerminalSupportFileNoticeReason)
);
}
export type OkPtyNotice =
| {
readonly ptyId: string;
readonly notice: 'invalid-shell-override';
readonly reason: TerminalShellNoticeReason;
}
| {
readonly ptyId: string;
readonly notice: 'shell-resolved';
readonly shellFamily: WindowsShellFamily;
}
| {
readonly ptyId: string;
readonly notice: 'support-file-degraded';
readonly reason: TerminalSupportFileNoticeReason;
};
export interface ClaudeReadiness {
readonly claude: 'present' | 'not-found' | 'unknown';
readonly mcpPreApprovable?: boolean;
readonly okToolsAutoApprovable?: boolean;
readonly mcpServerName?: string;
}
export interface CliReadiness {
readonly onPath: 'present' | 'not-found' | 'unknown';
readonly okServerConfigured?: boolean;
readonly mcpServerName?: string;
}
export interface CopyImageRequest {
readonly src: string;
}
export type CopyImageFailureReason =
| 'fetch-failed'
| 'path-escape'
| 'empty-image'
| 'read-error'
| 'write-error';
export type CopyImageResult =
| { ok: true }
| { ok: false; reason: CopyImageFailureReason; detail?: string };
export interface OkDesktopBridge {
readonly config: OkDesktopConfig;
onProjectSwitched(cb: (next: OkDesktopConfig) => void): OkUnsubscribe;
onMenuAction(cb: (action: OkMenuAction, origin: OkMenuActionOrigin) => void): OkUnsubscribe;
onUpdateDownloaded(cb: (info: OkUpdateDownloadedInfo) => void): OkUnsubscribe;
onUpdateRelaunching(cb: (info: OkUpdateRelaunchingInfo) => void): OkUnsubscribe;
onUpdateFetchingLatest(cb: (info: OkUpdateFetchingLatestInfo) => void): OkUnsubscribe;
onUpdateRelaunchFailed(cb: (info: OkUpdateRelaunchFailedInfo) => void): OkUnsubscribe;
onWhatsNew(cb: (info: OkWhatsNewInfo) => void): OkUnsubscribe;
onWhatsNewDismissed(cb: (info: { readonly version: string }) => void): OkUnsubscribe;
onUpdateStuckHint(cb: (info: OkUpdateStuckHintInfo) => void): OkUnsubscribe;
onUpdateManualCheck(cb: (info: OkUpdateManualCheckInfo) => void): OkUnsubscribe;
onDeepLink(cb: (evt: OkDeepLinkPayload) => void): OkUnsubscribe;
onShareReceived(cb: (payload: OkShareReceivedPayload) => void): OkUnsubscribe;
onServerVersionDrift(cb: (info: OkServerVersionDriftInfo) => void): OkUnsubscribe;
onServerRestarted(cb: (info: OkServerRestartedInfo) => void): OkUnsubscribe;
onRecentRemovedMissing(cb: (info: OkRecentRemovedMissingInfo) => void): OkUnsubscribe;
restartServer(projectPath: string): Promise<OkServerRestartOutcome>;
setThemeSource(source: OkThemeSource): Promise<{ ok: true }>;
setLanguagePreference(preference: LanguagePreference): Promise<{ ok: true }>;
userConfig?: OkUserConfigBridge;
signalThemeApplied(opts?: { reducedTransparency?: boolean; chrome?: OkChromeColors }): void;
dialog: {
openFolder(opts?: { defaultPath?: string }): Promise<string | null>;
};
shell: {
openExternal(url: string): Promise<void>;
detectProtocol(scheme: string): Promise<{ installed: boolean; displayName?: string }>;
spawnCursor(
path: string,
): Promise<
| { ok: true }
| { ok: false; reason: 'invalid-path' | 'not-installed' | 'timeout' | 'spawn-error' }
>;
recordHandoff(line: {
readonly target: 'claude-cowork' | 'claude-code' | 'codex' | 'cursor';
readonly host: 'electron' | 'web';
readonly outcome: 'ok' | 'error';
readonly ts: string;
readonly reason?: HandoffFailureReason;
readonly scope?: HandoffScope;
}): Promise<void>;
openAsset(relPath: string): Promise<OkAssetOpenResult>;
revealAsset(
relPath: string,
): Promise<{ ok: true } | { ok: false; reason: 'path-escape' | 'not-found' | 'resolve-error' }>;
revealExternal(
absPath: string,
): Promise<
| { ok: true; outcome: 'revealed' | 'dismissed' }
| { ok: false; reason: 'not-found' | 'invalid-path' | 'error' }
>;
showAssetMenu(params: {
readonly relPath: string;
readonly title: string;
readonly kind: 'asset' | 'wiki-link' | 'image';
}): Promise<void>;
showItemInFolder(path: string): Promise<void>;
trashItem(absPath: string): Promise<
| { ok: true }
| {
ok: false;
reason: 'not-found' | 'permission-denied' | 'system-error' | 'path-escape';
detail?: string;
}
>;
};
clipboard: {
writeText(text: string): Promise<void>;
copyImage(request: CopyImageRequest): Promise<CopyImageResult>;
};
project: {
listRecent(): Promise<RecentProjectEntry[]>;
removeRecent(path: string): Promise<void>;
getSessionState(): Promise<ProjectSessionState>;
setSessionState(state: ProjectSessionState): Promise<void>;
open(request: OkProjectOpenRequest): Promise<void>;
openFile(): Promise<void>;
createNew(args: {
parent: string;
name: string;
editors: OkMcpWiringEditorId[];
sharing?: 'shared' | 'local-only';
packId?: OkPackId;
rootDir?: string;
}): Promise<void>;
recordCreateNewBannerShown(banner: CreateNewBannerKind): Promise<void>;
checkTargetExists(request: {
projectPath: string;
kind: 'doc' | 'folder';
path: string;
}): Promise<OkCheckTargetExistsResult>;
readHeadBranch(projectPath: string): Promise<OkHeadBranchInfo>;
fetchBranchInfo(request: {
projectPath: string;
branch: string;
kind: 'doc' | 'folder';
path: string;
}): Promise<BranchInfoResponse | null>;
runCheckout(request: {
projectPath: string;
branch: string;
fastForward?: boolean;
}): Promise<CheckoutResponse | null>;
fetchTargetStatus(request: {
projectPath: string;
branch: string;
path: string;
kind: 'doc' | 'folder';
contentRootDepth?: number;
}): Promise<ShareTargetStatusResponse | null>;
awaitBranchSwitched(request: {
projectPath: string;
branch: string;
timeoutMs: number;
}): Promise<{ ok: true } | { ok: false; reason: 'timeout' | 'project-not-open' }>;
okInit(request: { projectPath: string }): Promise<LocalOpOkInitResponse>;
close(): Promise<void>;
};
worktree: {
list(): Promise<WorktreeListResult>;
inventory(request: WorktreeInventoryRequest): Promise<WorktreeInventoryResult>;
openInventory(request: WorktreeInventoryOpenRequest): Promise<WorktreeInventoryOpenResult>;
create(request: WorktreeCreateRequest): Promise<WorktreeCreateResult>;
checkout(request: { branch: string }): Promise<WorktreeCreateResult>;
};
sharing: {
status(): Promise<OkSharingStatusResult>;
setMode(mode: 'shared' | 'local-only'): Promise<OkSharingSetModeResult>;
};
slides: {
status(): Promise<OkSlidesStatusResult>;
open(docPath: string): Promise<OkSlidesOpenResult>;
};
bugReport: {
create(request: {
level: ReportBundleLevel;
note?: string;
includeCrashDump?: boolean;
includeScreenshot?: boolean;
attachments?: OkBugReportAttachmentInput[];
agentChatThreadId?: string;
crashEventId?: string;
}): Promise<OkBugReportCreateResult>;
captureScreenshot(): Promise<OkBugReportScreenshot | null>;
crashDumpAvailability(): Promise<OkBugReportCrashDumpAvailability>;
send(request: OkBugReportSendInput): Promise<OkBugReportSendResult>;
crashAck(request: { eventId: string }): Promise<OkBugReportCrashAckResult>;
list(): Promise<OkBugReportListResult>;
delete(id: string): Promise<OkBugReportDeleteResult>;
onCrashDetected(cb: (event: OkBugReportCrashDetectedEvent) => void): OkUnsubscribe;
};
assetUpload: {
uploadImage(request: OkAssetUploadRequest): Promise<OkAssetUploadResult>;
};
fs: {
defaultProjectsRoot(): Promise<string>;
folderState(path: string): Promise<OkFolderState>;
findEnclosingProjectRoot(path: string): Promise<OkFindEnclosingProjectRootResult | null>;
findEnclosingGitRoot(path: string): Promise<OkFindEnclosingGitRootResult | null>;
removeGitFolder(gitRoot: string): Promise<void>;
};
navigator: {
open(): Promise<void>;
};
noteWindow: {
open(
docName: string,
entryPoint: 'tab-menu' | 'palette',
): Promise<
| { ok: true; outcome: 'created' | 'focused' }
| { ok: false; reason: 'no-project' | 'invalid-request' }
>;
dispatchToMain(action: OkNoteWindowMainAction): Promise<OkNoteWindowMainActionResult>;
onMainAction(cb: (action: OkNoteWindowMainAction) => void): OkUnsubscribe;
};
seed: {
plan(options?: OkSeedPlanOptions): Promise<OkSeedPlanResult>;
apply(plan: OkScaffoldPlan, options?: OkSeedApplyOptions): Promise<OkSeedApplyResult>;
listPacks(): Promise<OkSeedListPacksResult>;
};
skill: {
detectClaudeDesktop(): Promise<boolean>;
buildAndOpen(opts?: { force?: boolean }): Promise<
| { ok: true; path: string; skipped?: false; version?: string }
| {
ok: true;
path?: undefined;
skipped: true;
version: string;
recordedAt?: string;
}
| {
ok: false;
reason: 'build-failed' | 'open-failed' | 'no-downloads-dir';
message?: string;
}
>;
};
update: {
relaunchNow(): Promise<void>;
checkNow(): Promise<void>;
dismissWhatsNew(version: string): Promise<void>;
dismissDownloaded(version: string): Promise<void>;
setMode(mode: OkUpdateMode): Promise<void>;
};
state: {
query(): Promise<OkStateSnapshot>;
resetIncompatible(): Promise<void>;
};
mcpWiring: {
onShow(cb: (payload: OkMcpWiringShowPayload) => void): OkUnsubscribe;
signalReady(): void;
confirm(request: OkMcpWiringConfirmRequest): Promise<OkMcpWiringResult>;
skip(): Promise<OkMcpWiringResult>;
reconfigure(): Promise<boolean>;
};
spellcheck: {
toggle(): Promise<boolean>;
languages(): Promise<OkSpellingLanguagesQueryResult>;
setLanguages(languages: readonly string[]): Promise<OkSpellingLanguagesSetResult>;
setEnabled(enabled: boolean): Promise<OkSpellcheckEnabledSetResult>;
};
integrations: {
status(): Promise<OkIntegrationsStatus>;
setComponent(request: OkIntegrationsSetRequest): Promise<OkIntegrationsSetResult>;
};
projectIntegrations: {
status(): Promise<OkProjectIntegrationsStatus>;
setComponent(request: OkProjectIntegrationsSetRequest): Promise<OkProjectIntegrationsSetResult>;
};
agentIntegrations: {
apply(request: OkAgentIntegrationsApplyRequest): Promise<OkAgentIntegrationsApplyResult>;
};
remoteAccess: {
probePort(port: number): Promise<boolean>;
};
onboarding: {
onShow(cb: (payload: OkOnboardingShowPayload) => void): OkUnsubscribe;
signalReady(): void;
confirm(request: OkOnboardingConfirmRequest): Promise<OkOnboardingResult>;
cancel(): Promise<OkOnboardingResult>;
probeContent(request: OkOnboardingProbeContentRequest): Promise<OkOnboardingProbeContentResult>;
onToast(cb: (payload: OkOnboardingToastPayload) => void): OkUnsubscribe;
};
localOp: {
auth: {
start(): OkLocalOpStream<OkLocalOpAuthEvent>;
};
clone: {
start(request: {
url: string;
dir: string;
branch?: string | null;
}): OkLocalOpStream<OkLocalOpCloneEvent>;
};
authStatus(request?: { host?: string }): Promise<OkLocalOpAuthStatusResponse>;
authRepos(request?: { host?: string }): Promise<OkLocalOpAuthReposResponse>;
};
share: {
validateLocalFolder(args: {
folderPath: string;
host: string;
owner: string;
repo: string;
}): Promise<ShareFolderValidationResult>;
};
editor: {
notifyActiveTargetChanged(target: OkEditorActiveTargetSnapshot): void;
notifyViewMenuStateChanged(state: OkEditorViewMenuStateChange): void;
notifyBackgroundThrottle(signal: { hasPendingWork: boolean; enabled: boolean }): void;
};
menu: {
dispatch(request: OkMenuUiDispatchRequest): Promise<OkMenuRendererSnapshot | undefined>;
};
startup: {
reportMarks(marks: { pageListReadyMs: number; firstContentMs: number }): void;
};
sidebar: {
expandAll(cb: () => void): OkUnsubscribe;
collapseAll(cb: () => void): OkUnsubscribe;
};
terminal: {
// STOP: create only reserves a session; install onData/onExit before start(ptyId) posts the deferred spawn in terminal-manager.ts.
create(opts: {
cols: number;
rows: number;
launchCommand?: string | TerminalLaunchCommand;
launchCli?: TerminalCli;
}): Promise<OkPtyCreateResult>;
input(ptyId: string, data: string): void;
resize(ptyId: string, cols: number, rows: number): void;
kill(ptyId: string): Promise<void>;
drain(ptyId: string, bytes: number): void;
list(): Promise<OkPtyListEntry[]>;
adopt(ptyId: string, opts?: { start?: boolean }): Promise<OkPtyAdoptResult>;
start(ptyId: string): Promise<OkPtyAdoptResult>;
setMeta(ptyId: string, meta: { customLabel?: string | null; ordinal?: number }): void;
setOrder(orderedPtyIds: readonly string[]): void;
getDockState(): Promise<OkTerminalDockState>;
setDockState(state: OkTerminalDockStateUpdate): Promise<OkTerminalDockStateWriteResult>;
onData(cb: (msg: OkPtyData) => void): OkUnsubscribe;
onExit(cb: (msg: OkPtyExit) => void): OkUnsubscribe;
onNotice(cb: (msg: OkPtyNotice) => void): OkUnsubscribe;
claudePreflight(): Promise<ClaudeReadiness>;
cliPreflight(cli: TerminalCli): Promise<CliReadiness>;
cliInstalledMap(): Promise<Partial<Record<TerminalCli, boolean>>>;
};
accessibility?: {
isScreenReaderActive(): boolean;
onScreenReaderChanged(cb: (active: boolean) => void): OkUnsubscribe;
};
readonly platform: HandoffHostPlatform;
readonly appVersion: string;
readonly instanceLabel: string | null;
readonly mcpServerName: string | null;
readonly cliCommandName: string | null;
getPathForFile(file: File): string | null;
setDisplayLockCrashKey(state: string): void;
debug?: {
keyringSmoke(): Promise<OkKeyringSmokeResult>;
};
}
declare global {
interface Window {
okDesktop?: OkDesktopBridge;
}
}