Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
46.0 KB
Raw Blame
/**
 * Shared contract for the Electron desktop IPC bridge.
 *
 * Producer: apps/desktop/electron/main.mjs — `desktopCommandHandlers`, typed
 * via JSDoc against `DesktopCommandHandlers` so missing/extra/renamed
 * commands fail `typecheck:electron`.
 * Consumer: apps/app/src/app/lib/desktop.ts — the `desktopBridge` Proxy and
 * its named exports derive per-command signatures from `DesktopCommandMap`.
 *
 * Every command sent over the `omnirush:desktop` channel has exactly one
 * entry here: `args` is the tuple the renderer passes, `result` what the
 * main process resolves. Results marked `unknown` are not yet modeled —
 * tighten them instead of widening call sites.
 */
import type { ConnectLinkVerifyFailure, ConnectLinkVerifyResult } from "./connect-link.js";
import type { WorkspaceWire } from "./workspace.js";

// ---------------------------------------------------------------------------
// Payload shapes (moved from apps/app/src/app/lib/desktop-types.ts, which
// re-exports them — keep that file as the app-side import path).
// ---------------------------------------------------------------------------

export type OpencodeExecutionEnvEntry = {
  name: string;
  value: string;
  redacted: boolean;
};

export type OpencodeExecutionSnapshot = {
  command: string;
  args: string[];
  cwd: string;
  env: OpencodeExecutionEnvEntry[];
};

export type EngineInfo = {
  running: boolean;
  runtime: "direct";
  managedByServer: boolean;
  baseUrl: string | null;
  projectDir: string | null;
  hostname: string | null;
  port: number | null;
  opencodeUsername: string | null;
  opencodePassword: string | null;
  opencodeBinPath: string | null;
  opencodeBinSource: string | null;
  pid: number | null;
  lastStdout: string | null;
  lastStderr: string | null;
  execution: OpencodeExecutionSnapshot | null;
};

export type DesktopNotificationInput = {
  title: string;
  body?: string;
  href?: string;
  silent?: boolean;
  /** The chat the notification is about: a click focuses the window and opens it. */
  sessionId?: string;
  workspaceId?: string;
};

/** Sent to the renderer when a notification about a chat is clicked. */
export type DesktopNotificationOpenSession = { sessionId: string; workspaceId?: string };

export type DesktopNotificationResult =
  | { ok: true }
  | { ok: false; reason: string };

export type DesktopIntegrationIssue =
  | "appimage-path"
  | "desktop-entry"
  | "icon"
  | "protocol-handler"
  | "version";

export type DesktopIntegrationStatus = {
  supported: boolean;
  state: "unsupported" | "not_integrated" | "integrated" | "needs_repair" | "managed_externally";
  ownership: "none" | "omnirush" | "external";
  appImagePath: string | null;
  desktopEntryPath: string | null;
  handlerDesktopId: string | null;
  issues: DesktopIntegrationIssue[];
};

export type DesktopIntegrationResult = {
  ok: boolean;
  status: DesktopIntegrationStatus;
  error?: string;
};

/** One built-in server or engine restart, as recorded in runtime-restarts.jsonl. */
export type OmniRushRuntimeRestartRecord = {
  at: string;
  kind: "server" | "engine";
  /** restarting, started, deferred, skipped, dropped, stopping, or restarted (engine watchdog). */
  action: string;
  reason: string;
  source: string;
  [key: string]: unknown;
};

export type OmniRushServerInfo = {
  running: boolean;
  /**
   * Monotonic per-start identity of the embedded server within this desktop
   * process. Sticky ports and persisted tokens keep the connection details
   * identical across restarts, so clients that must re-deliver state to a new
   * server lifetime (e.g. the Connect policy) key on this value. Null when
   * the bridge predates the field or no start completed yet.
   */
  generation: number | null;
  remoteAccessEnabled: boolean;
  host: string | null;
  port: number | null;
  baseUrl: string | null;
  connectUrl: string | null;
  mdnsUrl: string | null;
  lanUrl: string | null;
  clientToken: string | null;
  ownerToken: string | null;
  hostToken: string | null;
  managedOpencodeBinPath: string | null;
  managedOpencodeBinSource: string | null;
  /** Structured server log on disk, or null when the server runs without a file sink. */
  logFilePath: string | null;
  pid: number | null;
  lastStdout: string | null;
  lastStderr: string | null;
  managedOpencodeExecution: OpencodeExecutionSnapshot | null;
  /** Recent restarts, newest first (omnirushServerInfo only). */
  restarts?: OmniRushRuntimeRestartRecord[];
  /** An automatic restart that waits until no session is running. */
  pendingRestart?: { action: string; reason: string; source: string; requestedAt: string } | null;
  /** Set on an omnirushServerRestart answer that kept the running server. */
  restartDeferred?: boolean;
  restartSkipped?: boolean;
};

/** Outcome of the remote device-session revocation attempted during sign-out. */
export type OmniRushAccountSignOutReason =
  /** The account server accepted the revocation (2xx). */
  | "revoked"
  /** The account server no longer knows the device session (401/403, or a 404 naming the session). */
  | "already_revoked"
  /** The account server could not be reached or failed (network error, 5xx, other errors). */
  | "unreachable"
  /** The account server has no device sign-out route (404 route missing, 405, 501). */
  | "endpoint_missing";

export type OmniRushAccountSignOutResult = {
  connected: false;
  remoteRevoked: boolean;
  reason: OmniRushAccountSignOutReason;
};

/**
 * The account's tokens (/device/me `usage`). The first three are what can be
 * used now (the grant left plus the pot). With daily grants (`grantModel`
 * "daily"), `day` is today's allowance (resets 00:00 UTC), `week` the weekly
 * cap over it (resets Monday 00:00 UTC) and `pot` the one-time tokens used
 * once either runs out; `limitScope` "week" means only the weekly cap binds.
 * The grant fields are optional: an older desktop bridge leaves them out.
 */
export type OmniRushAccountUsage = {
  tokenLimit: number;
  usedTokens: number;
  remainingTokens: number;
  period?: "day" | "week";
  grantModel?: "weekly" | "daily" | null;
  limitScope?: "day" | "week" | null;
  day?: { allowance: number; used: number; reserved: number; resetsAt: string | null } | null;
  week?: { limit: number; used: number; resetsAt: string | null } | null;
  pot?: number;
};

/**
 * The account server's word on this app's version (/device/me
 * `client_update`, product "gui"). Required: update before `deadline`;
 * blocked: model requests are refused until the app is updated.
 */
export type OmniRushClientUpdate = {
  required: boolean;
  blocked: boolean;
  current: string | null;
  minimum: string | null;
  /** UTC ISO 8601. */
  deadline: string | null;
  message: string | null;
  downloadUrl: string | null;
};

/**
 * What the app shows for a mandatory update, derived in the Electron main
 * process from `client_update`, the gateway's `x-omnirush-update-required`
 * header and HTTP 426 `update_required` refusals.
 */
export type OmniRushUpdateGateState = {
  status: "none" | "required" | "blocked";
  current: string;
  minimum: string | null;
  deadline: string | null;
  message: string | null;
  downloadUrl: string;
  source: "profile" | "header" | "rejection" | null;
};

export type OmniRushQualityTier = "new" | "standard" | "gold" | "coaching" | "limited";

/**
 * Quality rewards (/device/me `quality`). Absent or null: the feature is
 * off and the app shows nothing. `preview`: spins pay 0 tokens.
 */
export type OmniRushAccountQuality = {
  tier: OmniRushQualityTier;
  /** 0..1 */
  score: number;
  /** Below 1 while "limited" and the cut is in force. */
  tokensMultiplier: number;
  spinsAvailable: number;
  /** Of `spinsAvailable`, those earned by reproducible sessions (always payable). */
  reproSpinsAvailable: number;
  /** Of `spinsAvailable`, those earned by client-grade sessions (the richer wheel). */
  clientSpinsAvailable: number;
  /** UTC ISO 8601, the soonest expiry. */
  spinsExpireAt: string | null;
  nextTierHint: string | null;
  tips: string[];
  /** Shown once per `id`; the same as `notices[0]`. */
  notice: OmniRushQualityNotice | null;
  /** Newest first, up to 5. */
  notices: OmniRushQualityNotice[];
  mode: "shadow" | "enforce";
  /** The daily budget is spent: only reproducible spins can be spun until tomorrow. */
  resting: boolean;
  preview: boolean;
  /** Consecutive UTC days with a reproducible session. */
  streakDays: number;
  /** Extra spins per reproducible good session right now. */
  streakMultiplier: number;
  streakNext: { days: number; bonusSpins: number } | null;
  /** How close the latest session is to earning a spin (progress 0..1). */
  nextSpinHint: { progress: number; text: string; sessionId: string | null } | null;
  /** Anonymised, across all accounts. */
  biggestWinToday: { tokens: number; at: string | null } | null;
  /** Shown once per `id`, only when the server sends one. */
  nudge: { id: string; text: string } | null;
  /** `windows_counts`: the server counts native-Windows sessions for a Good session ★. */
  windowsCounts: boolean;
};

export type OmniRushQualityNotice = { id: string; kind: string | null; title: string; body: string };

/** One session in GET /me/quality: why it earned (or did not earn) spins. */
export type OmniRushQualitySession = {
  sessionId: string;
  at: string | null;
  verdict: string | null;
  why: string | null;
  fails: string[];
  workspace: string | null;
  spins: number;
  counted: boolean;
  /** The reward level of reproducibility. */
  reproducible: "pass" | "fail" | "unknown" | null;
  /** The strict client grade. */
  reproClient: "pass" | "fail" | "unknown" | null;
  /** Client-grade: +2 spins, on the richer wheel. */
  clientGrade: boolean;
  /** The work-size step, 0..4. */
  workSize: number | null;
  work: { codeFiles: number; linesChanged: number; toolCalls: number; testRuns: number; floor: number; step: number } | null;
};

export type OmniRushQualityDetails = {
  segments: OmniRushWheelSegment[];
  /** The richer wheel client-grade spins use. */
  clientSegments: OmniRushWheelSegment[];
  expectedTokens: number | null;
  /** The top segment's prize. */
  jackpotTokens: number | null;
  sessions: OmniRushQualitySession[];
  /** `{code: label}` for the sessions' `fails`. */
  failLabels: Record<string, string>;
};

/**
 * The server's live status for one session (GET /me/sessions/{id}/status).
 * Labels, hints and messages are server text, shown as given. Null from the
 * desktop: the app falls back to its own checklist.
 */
/** Buildathon (GET /omnirush/me/buildathon), parsed by the main process; null unless enrolled. */
export type OmniRushBuildathonTrack = { id: string; label: string };
export type OmniRushBuildathonPhase = "upcoming" | "building" | "judging" | "results" | "closed";
export type OmniRushBuildathonEvent = {
  id: string;
  name: string;
  startsAt: string | null;
  registrationEndsAt: string | null;
  deadlineAt: string;
  resultsAt: string | null;
  phase: OmniRushBuildathonPhase | null;
  pageUrl: string | null;
  submitUrl: string | null;
  rules: string[];
  tracks: OmniRushBuildathonTrack[];
  /** Largest first. */
  reminders: Array<{ beforeSeconds: number; text: string }>;
};
export type OmniRushBuildathonParticipant = {
  enrolledAt: string | null;
  tokensGranted: number;
  tokensUsed: number;
  tokensLeft: number;
  sessionsTagged: number;
  sessionsGood: number;
};
export type OmniRushBuildathonSubmission = {
  submissionId: string;
  submittedAt: string | null;
  updatedAt: string | null;
  track: string | null;
  title: string | null;
  repoUrl: string | null;
  demoVideoUrl: string | null;
  liveUrl: string | null;
  sessionIds: string[];
  checks: Array<{ id: string; ok: boolean; text: string }>;
  locked: boolean;
};
/** The event's reproducibility settings (defaults when the server sends none). */
export type OmniRushBuildathonRepro = {
  box: "on" | "offer" | "off";
  agentRules: string;
  checklist: Array<{ id: string; text: string }>;
};
export type OmniRushBuildathonCheck = { id: string; text: string; ok: boolean | null };
export type OmniRushBuildathonStatus = {
  enrolled: true;
  serverTime: string | null;
  event: OmniRushBuildathonEvent;
  participant: OmniRushBuildathonParticipant | null;
  submission: OmniRushBuildathonSubmission | null;
  repro: OmniRushBuildathonRepro;
  /** The updates feed, newest first (at most 20). */
  announcements: OmniRushBuildathonAnnouncement[];
  /** The linked GitHub account (needed to submit); null when none is linked. */
  github: { login: string; linkedAt: string | null } | null;
};
export type OmniRushBuildathonAnnouncement = {
  id: string;
  title: string;
  /** Plain text; may contain URLs. */
  body: string;
  url: string | null;
  level: "info" | "important";
  publishedAt: string | null;
};
/** A non-participant's promo (GET /me/buildathon `enrolled: false` + `promo`). */
export type OmniRushBuildathonPromo = {
  /** The dismissal key: a new id shows the promo again. */
  id: string;
  title: string;
  text: string | null;
  ctaLabel: string;
  ctaUrl: string | null;
  /** Registration close: hidden after it. */
  endsAt: string | null;
  /** True: open joining (on the web at `joinUrl`, which links GitHub; without one, POST /me/buildathon/join). */
  join: boolean;
  joinUrl: string | null;
};
export type OmniRushBuildathonPromoStatus = { enrolled: false; serverTime: string | null; promo: OmniRushBuildathonPromo };
/** What the app reads from GET /me/buildathon: a participant, a promo, or nothing to show. */
export type OmniRushBuildathonAnswer = OmniRushBuildathonStatus | OmniRushBuildathonPromoStatus | null;
export type OmniRushBuildathonSession = {
  sessionId: string;
  title: string | null;
  project: string | null;
  startedAt: string | null;
  endedAt: string | null;
  track: string | null;
  status: "good" | "pending" | "incomplete";
  reasons: string[];
  tokens: number;
};
export type OmniRushBuildathonLinkResult =
  | { ok: true; status: OmniRushBuildathonStatus }
  | { ok: false; error: string; closed?: boolean };
export type OmniRushBuildathonTagResult = "tagged" | "refused" | "retry";

/** A sponsored placement as the window draws it (apps/desktop/electron/placements/placements.mjs placementView). */
export type OmniRushPlacementSlot = "home_banner" | "turn_footer";
export type OmniRushPlacementSurface = "desktop_home" | "desktop_turn";
export type OmniRushPlacement = {
  id: string;
  /** This display's id (a random UUID made by the main process); every event about it carries it. */
  displayId: string;
  surface: OmniRushPlacementSurface;
  slot: OmniRushPlacementSlot;
  /** "Sponsored · <sponsor>" */
  label: string;
  sponsor: string;
  /** Plain text, at most 60 characters. */
  title: string;
  /** Plain text, at most 140 characters (may be empty). */
  body: string;
  /** At most 20 characters. */
  ctaLabel: string;
  /** https only; opened by the main process after a click. */
  url: string;
  /** https only, or null. */
  imageUrl: string | null;
  snoozeDays: number;
};
/** rendered / viewable / open (the click) / dismiss: about one display; conversation / activity: for the display rotation. */
export type OmniRushPlacementAction = "rendered" | "viewable" | "open" | "dismiss" | "conversation" | "activity";

/** In-app feedback (apps/desktop/electron/feedback-desktop.mjs and the shared feedback/feedback.mjs). */
export type OmniRushFeedbackKind = "turn" | "general" | "pulse";
export type OmniRushFeedbackTrigger = "sampled" | "command" | "menu" | "pulse";
/** How a finished turn ended: only "ok" turns may get the after-turn prompt. */
export type OmniRushFeedbackTurnOutcome = "ok" | "refused" | "limit" | "error" | "stopped";
export type OmniRushFeedbackPolicy = {
  enabled: boolean;
  turnSampleRate: number;
  maxPerDay: number;
  pulseEnabled: boolean;
  pulseAfterSessions: number;
  pulseEveryDays: number;
};
export type OmniRushFeedbackOffer = { kind: "turn" | "pulse" } | null;
export type OmniRushFeedbackInput = {
  kind: OmniRushFeedbackKind;
  /** "up" | "down" for a turn, 0-10 for the pulse, null for anytime feedback. */
  rating: "up" | "down" | number | null;
  categories: string[];
  comment: string | null;
  sessionId: string | null;
  /** 1-based user-turn index of the rated answer. */
  turn: number | null;
  trigger: OmniRushFeedbackTrigger;
  modelId: string | null;
  effort: string | null;
};
/**
 * queued: kept in feedback.json and sent later (offline, signed out, the
 * server has none yet, rate limited). ok false: not sent and not kept: the
 * input ("comment", "kind", "rating"), or the server refused it ("invalid":
 * a 422 with its wrong fields in `errors`; "too_large": a 413).
 */
export type OmniRushFeedbackResult =
  | { ok: true; sent: boolean; queued: boolean; reason?: "offline" | "signed_out" | "unavailable" | "rate_limited" }
  | { ok: false; error: string; errors?: Record<string, string> | null };
export type OmniRushFeedbackStatus = { policy: OmniRushFeedbackPolicy; queued: number; unavailable: boolean; allowed: boolean };

export type OmniRushSessionStatus = {
  sessionId: string;
  status: "on_track" | "at_risk" | "failing" | "unknown";
  reasons: { code: string; message: string }[];
  /** The headline above the checklist. */
  message: string | null;
  dock: {
    mode: "off" | "observe" | "warn" | "enforce";
    stage: "none" | "warn" | "surcharge" | "cap";
    weight: number;
    sessionTokens: number;
    surchargeTokens: number;
    capAtTokens: number | null;
    capped: boolean;
    message: string | null;
    link: string | null;
  } | null;
  verdict: { state: "pending" | "usable" | "not_usable"; reasons: string[]; rewardWeight: number | null } | null;
  /**
   * Whether the session was delivered and, when not, why (`delivery`; on
   * servers without it, read from a not_usable verdict's reasons). A reason
   * without the server's message has `message: null` (the app words it).
   */
  delivery?: { state: "delivered" | "not_delivered" | "pending"; reasons: { code: string; message: string | null }[]; message?: string | null } | null;
  /** In order; ids may grow. */
  checklist: { id: string; state: "pass" | "fail" | "warn" | "pending"; label: string; hint: string }[];
  evaluatedAt: string | null;
  /**
   * Server switches for the client; null on older servers (no auto-retry,
   * finish guard and one-more-turn nudge on).
   */
  client: {
    /** Send `message` once after a turn ends on a gateway, stream or tool-chain error (at most `max` in a row). */
    autoRetry: { enabled: boolean; max: number; message: string | null } | null;
    /** false: the finish guard's cut/awaiting states are off. */
    finishGuard: boolean;
    /** false: no one-more-turn nudge from the `depth` item. */
    oneMoreTurn: boolean;
  } | null;
  /** How often to re-ask while the session is active: 30 or more. */
  pollSeconds: number;
};

export type OmniRushQualitySpinRecord = {
  id: string;
  status: "ready" | "spun" | "expired" | "forfeit";
  reason: string | null;
  reproducible: boolean;
  /** Earned by a replay-ready (client-grade) session. */
  clientGrade: boolean;
  sessionId: string | null;
  earnedAt: string | null;
  expiresAt: string | null;
  spunAt: string | null;
  prizeTokens: number | null;
  paidTokens: number | null;
};

/**
 * Keep this computer awake while the agent works (apps/desktop/electron/keep-awake.mjs).
 * `available`: false over SSH or in CI, where it never runs; `forcedOff`: OMNIRUSH_KEEP_AWAKE=0 for this launch.
 */
export type KeepAwakeState = { enabled: boolean; active: boolean; available: boolean; forcedOff: boolean };

/** GET /me/quality/spins: totals and the newest spins (up to 10). */
export type OmniRushQualitySpinTotals = { spun: number; paidTokens: number; recent: OmniRushQualitySpinRecord[] };

export type OmniRushWheelSegment = { tokens: number; weight: number };

/** A 200 from POST /me/quality/spin. The server picks `segmentIndex`; the app only animates to it. */
export type OmniRushQualitySpin = {
  /** Paid into the pot: 0 in preview or past the pot cap. */
  tokens: number;
  /** The segment the wheel landed on. */
  prizeTokens: number;
  segmentIndex: number;
  segments: OmniRushWheelSegment[];
  preview: boolean;
  capped: boolean;
  reproducible: boolean;
  alreadySpun: boolean;
  spunAt: string | null;
  spinsAvailable: number;
  potBalance: number | null;
  /** big: prize >= 2M; jackpot: the top segment. */
  celebrate: "none" | "big" | "jackpot";
  /** Landed next to the jackpot. */
  nearMiss: boolean;
  jackpotTokens: number | null;
  streakDays: number | null;
  /** Earned by a client-grade session; spun on the richer wheel. */
  clientGrade: boolean;
};

export type OmniRushQualitySpinRefusal = "no_spins" | "wheel_resting" | "quality_rewards_off";

export type OmniRushQualitySpinOutcome =
  | { ok: true; spin: OmniRushQualitySpin }
  | { ok: false; reason: OmniRushQualitySpinRefusal | "signed_out" | "unreachable" | "failed"; status: number | null };

export type OmniRushAccountStatus = {
  connected: boolean;
  gatewayConfigured: boolean;
  reauthorizationRequired?: boolean;
  /** The account's opaque id (UUID) from /device/me; product analytics are linked to it. */
  accountId?: string | null;
  email?: string | null;
  displayName?: string | null;
  accountStatus?: string | null;
  usage?: OmniRushAccountUsage | null;
  /** Gateway URL the connected account uses, or the configured default while signed out. */
  gatewayUrl?: string | null;
  /** Display label for the account server, e.g. "omnirush.ai" or "localhost:8090 (local API)". */
  gatewayHost?: string | null;
  /**
   * "file": Linux without a usable keyring, so the sign-in is kept in an
   * owner-only file on this computer. Absent when a keyring protects it.
   */
  credentialStorage?: "file";
  /**
   * Linux: a sign-in sealed by a system keyring is on disk but no keyring is
   * usable now, so the user is asked to sign in again. Distinct from a
   * session the server ended (reauthorizationRequired alone).
   */
  keyringUnavailable?: boolean;
  /** /device/me `client_update` for this app; absent from an older desktop bridge. */
  clientUpdate?: OmniRushClientUpdate | null;
  /** Quality rewards; null (or absent from an older bridge) while the feature is off. */
  quality?: OmniRushAccountQuality | null;
  /** Hackathons the account takes part in (events/app-events.mjs); null or absent: show nothing. */
  events?: OmniRushAccountEvents | null;
  /** Main process only: /device/me's raw events part, kept on disk and replaced by `events` before the window gets the status. */
  eventsRecord?: unknown;
};

export type OmniRushAccountEvents = {
  /** Running now, the one ending first first. `title` "BIOS V2 hackathon", `detail` "You're participating · ends Fri 6:00 PM", `ends` its last part. */
  active: Array<{ name: string; endsAt: string; title: string; detail: string; ends: string }>;
  /** Joined, newest first; `date` "Oct 29, 2026" (local). */
  joined: Array<{ name: string; joinedAt: string; date: string }>;
  /** The app has to start again for the event (it applies from the next start). */
  restart: boolean;
};

export type EngineDoctorResult = {
  found: boolean;
  inPath: boolean;
  resolvedPath: string | null;
  resolvedSource: string | null;
  version: string | null;
  supportsServe: boolean;
  notes: string[];
  serveHelpStatus: number | null;
  serveHelpStdout: string | null;
  serveHelpStderr: string | null;
};

export type WorkspaceList = {
  selectedId?: string;
  watchedId?: string | null;
  activeId?: string | null;
  workspaces: WorkspaceWire[];
};

export type WorkspaceExportSummary = {
  outputPath: string;
  included: number;
  excluded: string[];
};

export type BrandIconApplyResult = { ok: boolean; reason?: string };
export type BrandIconState = { applied: boolean; sourceUrl: string | null; reason: string | null };
export type EvalRelaunchResult = { ok: true };

export type OpencodeCommandDraft = {
  name: string;
  description?: string;
  template: string;
  agent?: string;
  model?: string;
  subtask?: boolean;
};

export type WorkspaceOmniRushConfig = {
  version: number;
  workspace?: {
    name?: string | null;
    createdAt?: number | null;
    preset?: string | null;
  } | null;
  authorizedRoots: string[];
  reload?: {
    auto?: boolean;
    resume?: boolean;
  } | null;
};

export type AppBuildInfo = {
  version: string;
  gitSha?: string | null;
  buildEpoch?: string | null;
  omnirushDevMode?: boolean;
  os?: string | null;
  arch?: string | null;
};

export type DesktopDistributionInfo = {
  flavor: "public" | "enterprise";
  appName: string;
  appIdentifier: string;
  protocolScheme: string;
  requireSignin: boolean;
  requireActivation: boolean;
};

/** Org + first-skill identity shared by the handoff and prepared records. */
export type DesktopBootstrapOrgSkill = {
  orgId: string;
  orgName: string;
  orgSlug: string;
  skillId: string;
  skillTitle: string;
};

export type DesktopBootstrapConfig = {
  baseUrl: string;
  apiBaseUrl?: string | null;
  requireSignin: boolean;
  requireActivation?: boolean;
  brandAppName?: string | null;
  brandLogoUrl?: string | null;
  brandIconUrl?: string | null;
  writtenAt?: string | null;
  fromFile?: boolean;
  claimLinks?: Array<{
    id: string;
    role: string;
    token?: string;
    url: string;
    expiresAt: string;
  }> | null;
  handoff?: (DesktopBootstrapOrgSkill & {
    grant: string;
    denBaseUrl: string;
    createdAt: string;
  }) | null;
  prepared?: (DesktopBootstrapOrgSkill & {
    skillsDir: string;
    skillPath: string;
    preparedAt: string;
  }) | null;
  enterpriseActivation?: {
    activatedAt: string;
    denBaseUrl: string;
  } | null;
};

export type OmniRushDockerCleanupResult = {
  candidates: string[];
  removed: string[];
  errors: string[];
};

export type ExecResult = {
  ok: boolean;
  status: number;
  stdout: string;
  stderr: string;
};

export type LocalSkillCard = {
  name: string;
  path: string;
  description?: string;
  trigger?: string;
};

export type SkillFolderRead = {
  root: string;
  /** The folder's basename. */
  name: string;
  files: Array<{ path: string; contentBase64: string; executable: boolean }>;
  skipped: string[];
};

export type LocalSkillContent = {
  path: string;
  content: string;
};

export type OpencodeConfigFile = {
  path: string;
  exists: boolean;
  content: string | null;
};

export type UpdaterEnvironment = {
  supported: boolean;
  reason: string | null;
  executablePath: string | null;
  appBundlePath: string | null;
};

export type CacheResetResult = {
  removed: string[];
  missing: string[];
  errors: string[];
};

export type NukeManifestPreview = {
  deletePaths: string[];
  bootstrapPath: string;
  preserveBootstrapPath: string | null;
  partitions: string[];
};

export type NukeOptions = {
  preserveBootstrap: boolean;
};

export type NukeReceiptError = {
  path: string;
  message: string;
  code?: string;
};

export type NukeReceipt = {
  deleted: string[];
  pendingRetry: string[];
  errors: NukeReceiptError[];
  preservedBootstrap: boolean;
  relaunchMode: "cleanup_worker" | "direct";
  workerScheduled: boolean;
};

export type DesktopFetchInit = {
  method?: string;
  headers?: Record<string, string>;
  body?: string;
  timeoutMs?: number;
  agentContextDiagnostics?: {
    deadlineAtMs: number;
  };
};

export type DesktopFetchResult = {
  status: number;
  statusText: string;
  headers: [string, string][];
  body: string;
};

export type DesktopMultipartUploadInput = {
  transferId: string;
  url: string;
  bytes: ArrayBuffer;
  filename: string;
  size: number;
  contentType?: string;
  fieldName?: string;
  fields?: Record<string, string>;
  method?: string;
  headers?: Record<string, string>;
  timeoutMs?: number;
};

export type DesktopBinaryDownloadInput = {
  transferId: string;
  url: string;
  destinationPath: string;
  maxBytes?: number;
  method?: string;
  headers?: Record<string, string>;
  timeoutMs?: number;
};

export type DesktopBinaryDownloadResult = {
  status: number;
  statusText: string;
  headers: [string, string][];
  path: string | null;
  bytes: number;
  body?: string;
};

export type WorkspaceCreateInput = {
  folderPath: string;
  name?: string | null;
  preset?: string | null;
};

export type WorkspaceCreateRemoteInput = {
  baseUrl: string;
  remoteType?: "omnirush" | "opencode" | null;
  directory?: string | null;
  displayName?: string | null;
  omnirushHostUrl?: string | null;
  omnirushToken?: string | null;
  omnirushClientToken?: string | null;
  omnirushHostToken?: string | null;
  omnirushWorkspaceId?: string | null;
  omnirushWorkspaceName?: string | null;
  sandboxBackend?: string | null;
  sandboxRunId?: string | null;
  sandboxContainerName?: string | null;
};

export type WorkspaceUpdateRemoteInput = WorkspaceCreateRemoteInput & {
  workspaceId: string;
};

export type UiControlBridgeInfo = {
  baseUrl?: string;
  token?: string;
};

export type ComputerUsePermissions = {
  platform?: string;
  modes?: string[];
  backgroundControl?: boolean;
  ok: boolean;
  accessibility: boolean;
  screenRecording: boolean;
  supported?: boolean;
  protocolVersion?: string;
  error?: string;
};

export type RunningAppsResult = {
  ok: boolean;
  apps: string[];
};

/** Computer use (contract v2): the app identity the host verified (exe path / bundle id, pid; none on the agent's own display). */
export type ComputerUseAppRef = { app_id: string; app_name: string; bundle_or_exe: string; pid: number | null };

/** A point in the session's frame pixels. */
export type ComputerUsePoint = { x: number; y: number };

/** The agent cursor's latest move (before a pointer act): the live view glides it from `from` to `to`. */
export type ComputerUseCursorMove = { session_id: string; from: ComputerUsePoint | null; to: ComputerUsePoint; path: ComputerUsePoint[]; action: string; width: number; height: number; seq: number; at: number };

/** One computer use session as the host sees it (apps/server/src/computer-use/shared/portable-host.mjs, virtual-host.mjs). */
export type ComputerUseSessionState = {
  id: string;
  phase: "working" | "paused" | "ended";
  mode: "observe" | "control";
  purpose: string;
  status: string;
  app: ComputerUseAppRef;
  window: { id: string; title: string };
  windows: Array<{ id: string; title: string }>;
  /** "setting": the person's screen (the person's real-screen setting); "virtual": the agent's own display. */
  approval: "setting" | "virtual" | null;
  actions: number;
  actions_left: number;
  seconds_left: number;
  can_continue: boolean;
  log: Array<{ at: string; action: string; intent: string; ok: boolean; code: string | null }>;
  frame: { sha: string; width: number; height: number; mime: string; data_url: string; at: string; cursor?: ComputerUsePoint | null } | null;
  chat: string | null;
  hidden?: boolean;
  window_bounds?: { x: number; y: number; width: number; height: number };
  /** The agent's own display. */
  display?: "virtual";
  virtual?: { kind: string; display: string; browser: string | null };
  /** The agent's cursor in frame pixels (the agent's own display). */
  cursor?: ComputerUsePoint | null;
  cursor_move?: ComputerUseCursorMove;
};

/** The pressed button's box (CSS pixels of the main window): the person's own press must land in it (Continue). */
export type ComputerUseButtonRect = { x: number; y: number; width: number; height: number };
export type ComputerUseControlAction = "stop" | "takeover" | "continue" | "hide" | "show";

export type ComputerUseStatus = {
  enabled: boolean;
  supported: boolean;
  /** Why it is off or unavailable (people-facing), when it is. */
  message: string | null;
  /** The person's own on/off for this device (on by default). */
  device_on?: boolean;
  /** The models that can use computer use (null: any). */
  models?: string[] | null;
  mode: "careful" | "normal" | "auto";
  sessions: ComputerUseSessionState[];
};

/** The person's one-time setting for their own screen (off by default). forced: the environment decides; allowed: the server allows it. */
/** `on`: this computer's own setting; `allowed`: the server's yes for the account (its opt-in, set only in the web console), read just now. Both are needed. */
export type ComputerUseRealScreen = { on: boolean; forced: boolean; allowed: boolean };

// ---------------------------------------------------------------------------
// The command map
// ---------------------------------------------------------------------------

export type DesktopCommandMap = {
  // Workspace state
  workspaceBootstrap: { args: []; result: WorkspaceList };
  workspaceSetSelected: { args: [workspaceId: string]; result: WorkspaceList };
  workspaceSetRuntimeActive: { args: [workspaceId: string | null]; result: WorkspaceList };
  workspaceCreate: { args: [input: WorkspaceCreateInput]; result: WorkspaceList };
  workspaceCreateRemote: { args: [input: WorkspaceCreateRemoteInput]; result: WorkspaceList };
  workspaceUpdateRemote: { args: [input: WorkspaceUpdateRemoteInput]; result: WorkspaceList };
  workspaceUpdateDisplayName: {
    args: [input: { workspaceId: string; displayName?: string | null }];
    result: WorkspaceList;
  };
  workspaceForget: { args: [workspaceId: string]; result: WorkspaceList };
  workspaceAddAuthorizedRoot: {
    args: [input: { workspacePath: string; folderPath?: string; authorizedRoot?: string }];
    result: unknown;
  };
  workspaceOmniRushRead: {
    args: [input: { workspacePath: string }];
    result: WorkspaceOmniRushConfig;
  };
  workspaceOmniRushWrite: {
    args: [input: { workspacePath: string; config: WorkspaceOmniRushConfig }];
    result: unknown;
  };
  workspaceExportConfig: {
    args: [input: { workspaceId: string; outputPath: string }];
    result: WorkspaceExportSummary;
  };
  workspaceImportConfig: {
    args: [input: { archivePath: string; targetDir: string; name?: string | null }];
    result: unknown;
  };

  // Opencode custom commands
  opencodeCommandList: {
    args: [input: { scope: string; projectDir?: string }];
    result: string[];
  };
  opencodeCommandWrite: {
    args: [input: { scope: string; projectDir?: string; command: OpencodeCommandDraft }];
    result: unknown;
  };
  opencodeCommandDelete: {
    args: [input: { scope: string; projectDir?: string; name: string }];
    result: unknown;
  };

  // Engine / runtime lifecycle
  engineStart: { args: [projectDir: string, options?: Record<string, unknown>]; result: EngineInfo };
  prepareFreshRuntime: { args: []; result: unknown };
  runtimeBootstrap: { args: []; result: unknown };
  runtimeStatus: { args: []; result: unknown };
  engineStop: { args: []; result: EngineInfo };
  engineRestart: { args: [options?: Record<string, unknown>]; result: EngineInfo };
  engineInfo: { args: []; result: EngineInfo };
  engineDoctor: { args: [projectDir?: string]; result: EngineDoctorResult };
  engineInstall: { args: []; result: unknown };

  // App / bridge info
  appBuildInfo: { args: []; result: AppBuildInfo };
  desktopNotificationShow: {
    args: [input: DesktopNotificationInput];
    result: DesktopNotificationResult;
  };
  desktopSentrySetSession: {
    args: [input: { userId: string; orgId: string }];
    result: { enabled: boolean };
  };
  desktopSentryClearSession: { args: []; result: { enabled: boolean } };
  /** Consent for desktop error reports; the app no longer grants it. */
  desktopSentrySetConsent: { args: [enabled: boolean]; result: { enabled: boolean } };
  desktopIntegrationStatus: { args: []; result: DesktopIntegrationStatus };
  desktopIntegrationInstall: {
    args: [options?: { useExternalLauncher?: boolean }];
    result: DesktopIntegrationResult;
  };
  desktopIntegrationRemove: { args: []; result: DesktopIntegrationResult };
  getUiControlBridgeInfo: { args: []; result: UiControlBridgeInfo | null };
  getOmniRushUiMcpCommand: { args: []; result: string[] };
  getComputerUseMcpCommand: { args: []; result: string[] };
  getComputerUseMcpEnvironment: { args: []; result: Record<string, string> };
  getComputerUseState: { args: []; result: ComputerUseStatus };
  getComputerUseRealScreen: { args: []; result: ComputerUseRealScreen };
  setComputerUseRealScreen: { args: [on: boolean]; result: ComputerUseRealScreen };
  setComputerUseOn: { args: [on: boolean]; result: ComputerUseStatus };
  computerUseControl: { args: [value: { session_id: string; action: ComputerUseControlAction; rect?: ComputerUseButtonRect }]; result: void };
  getOmniRushUiMcpEnvironment: { args: []; result: Record<string, string> };

  // Computer use
  checkComputerUsePermissions: { args: []; result: ComputerUsePermissions };
  listRunningApps: { args: []; result: RunningAppsResult };
  openComputerUsePermissionSetup: { args: []; result: ComputerUsePermissions };
  openComputerUsePermissionSettings: { args: []; result: unknown };

  // Bootstrap config
  getDesktopBootstrapConfig: { args: []; result: DesktopBootstrapConfig };
  debugDesktopBootstrapConfig: { args: []; result: unknown };
  clearDesktopBootstrapConfig: { args: []; result: unknown };
  setDesktopBootstrapConfig: {
    args: [config: Partial<DesktopBootstrapConfig>];
    result: DesktopBootstrapConfig;
  };

  // Connect links use a short-lived HTTPS exchange by default and can use an
  // embedded-key signed token when explicitly enabled. The renderer relays
  // only the raw URL. `connectLinkAccept` resolves it again after confirmation,
  // enforces one-time use, and persists the target as desktop bootstrap config.
  connectLinkVerify: { args: [rawUrl: string]; result: ConnectLinkVerifyResult };
  connectLinkAccept: {
    args: [rawUrl: string];
    result: { ok: true; config: DesktopBootstrapConfig } | ConnectLinkVerifyFailure;
  };
  nukeOmniRushAndOpencodeConfigPreview: { args: [options?: NukeOptions]; result: NukeManifestPreview };
  nukeOmniRushAndOpencodeConfigAndExit: { args: [options?: NukeOptions]; result: NukeReceipt };

  // Sandbox
  sandboxCleanupOmniRushContainers: { args: []; result: OmniRushDockerCleanupResult };

  // OmniRush.ai server sidecar
  omnirushServerInfo: { args: []; result: OmniRushServerInfo };
  omnirushAccountStatus: {
    args: [options?: { sessionId?: string | null }];
    result: OmniRushAccountStatus;
  };
  omnirushQualityDetails: { args: []; result: OmniRushQualityDetails | null };
  omnirushQualitySpins: { args: []; result: OmniRushQualitySpinTotals | null };
  keepAwakeStatus: { args: []; result: KeepAwakeState };
  keepAwakeSet: { args: [enabled: boolean]; result: KeepAwakeState };
  omnirushSessionStatus: { args: [input: { sessionId: string }]; result: OmniRushSessionStatus | null };
  omnirushQualitySpin: {
    args: [input: { idempotencyKey: string }];
    result: OmniRushQualitySpinOutcome;
  };
  omnirushBuildathon: { args: []; result: OmniRushBuildathonAnswer };
  omnirushBuildathonJoin: { args: []; result: OmniRushBuildathonLinkResult };
  omnirushPlacement: { args: [input: { slot: OmniRushPlacementSlot; sessionId?: string }]; result: OmniRushPlacement | null };
  omnirushPlacementAction: { args: [input: { action: OmniRushPlacementAction; id?: string; displayId?: string; sessionId?: string }]; result: { ok: boolean; opened?: boolean; rotate?: boolean } };
  omnirushFeedbackPolicy: { args: []; result: OmniRushFeedbackPolicy };
  omnirushFeedbackStatus: { args: []; result: OmniRushFeedbackStatus };
  omnirushFeedbackSessionStarted: { args: [input: { sessionId: string }]; result: boolean };
  omnirushFeedbackOffer: {
    args: [input: { sessionId: string; outcome: OmniRushFeedbackTurnOutcome; toolCalls: number; durationMs: number; text?: string }];
    result: OmniRushFeedbackOffer;
  };
  omnirushFeedbackShown: { args: [input: { kind: "turn" | "pulse" }]; result: { ok: boolean } };
  omnirushFeedbackSubmit: { args: [input: OmniRushFeedbackInput]; result: OmniRushFeedbackResult };
  omnirushBuildathonSessions: { args: []; result: OmniRushBuildathonSession[] | null };
  omnirushBuildathonLink: { args: [input: { code: string }]; result: OmniRushBuildathonLinkResult };
  omnirushBuildathonChecklist: {
    args: [input: { path: string; checklist: Array<{ id: string; text: string }> }];
    result: OmniRushBuildathonCheck[] | null;
  };
  omnirushBuildathonTagSession: {
    args: [input: { sessionId: string; track: string; project?: string | null }];
    result: OmniRushBuildathonTagResult;
  };
  omnirushAccountConnect: {
    args: [options?: { gatewayUrl?: string; deviceName?: string }];
    result: { connected: true; userCode: string };
  };
  omnirushAccountSignOut: { args: []; result: OmniRushAccountSignOutResult };
  automationRunnerConfigure: {
    args: [configuration: { baseUrl: string; token: string; runnerId: string } | null];
    result: { connected: boolean };
  };
  omnirushServerRestart: {
    args: [options?: Record<string, unknown>];
    result: OmniRushServerInfo;
  };

  // Dialogs
  pickDirectory: {
    args: [options?: { title?: string; defaultPath?: string; multiple?: boolean }];
    result: string | string[] | null;
  };
  pickFile: {
    args: [
      options?: {
        title?: string;
        defaultPath?: string;
        multiple?: boolean;
        filters?: { name: string; extensions: string[] }[];
      },
    ];
    result: string | string[] | null;
  };
  saveFile: {
    args: [options?: { title?: string; defaultPath?: string; filters?: { name: string; extensions: string[] }[] }];
    result: string | null;
  };

  // Skills
  importSkill: {
    args: [projectDir: string, sourceDir: string, options?: { overwrite?: boolean }];
    result: ExecResult;
  };
  /** Reads a picked/dropped skill folder for upload (links refused, junk skipped, capped). */
  readSkillFolder: { args: [sourceDir: string]; result: SkillFolderRead };
  installSkillTemplate: {
    args: [projectDir: string, name: string, content: string, options?: { overwrite?: boolean }];
    result: ExecResult;
  };
  listLocalSkills: { args: [projectDir: string]; result: LocalSkillCard[] };
  readLocalSkill: { args: [projectDir: string, skillName: string]; result: LocalSkillContent };
  writeLocalSkill: {
    args: [projectDir: string, skillName: string, content: string];
    result: ExecResult;
  };
  uninstallSkill: { args: [projectDir: string, skillName: string]; result: ExecResult };

  // Updater / config / resets
  updaterEnvironment: { args: []; result: UpdaterEnvironment };
  readOpencodeConfig: { args: [scope: string, projectDir?: string]; result: OpencodeConfigFile };
  writeOpencodeConfig: {
    args: [scope: string, projectDir: string, content: string];
    result: ExecResult;
  };
  /**
   * The renderer passes its reset-modal mode, but the main process currently
   * IGNORES it and always removes workspace state + bootstrap config; only
   * the renderer's localStorage cleanup is mode-scoped. Follow-up: decide
   * whether "onboarding" should preserve desktop workspace state.
   */
  resetOmniRushState: { args: [mode?: "onboarding" | "all"]; result: unknown };
  resetOpencodeCache: { args: []; result: CacheResetResult };
  opencodeMcpAuth: { args: [action: string, name: string]; result: ExecResult };
  setWindowDecorations: { args: [decorated: boolean]; result: unknown };

  /** Opens <userData>/logs in the system file manager. Takes no path from the renderer. */
  openLogsFolder: { args: []; result: { ok: boolean; error?: string } };
  /** Settings > Storage. Lists (dryRun) or removes what the app no longer needs; takes no path from the renderer. */
  freeUpSpace: {
    args: [options?: { dryRun?: boolean }];
    result: {
      ok: boolean;
      skipped: string | null;
      dryRun: boolean;
      freedBytes: number;
      freed: string;
      items: Array<{ kind: string; path: string; bytes: number; size: string; reason: string; inUse: boolean }>;
    };
  };

  // Window / OS utilities (dunder commands)
  __openPath: { args: [target: string]; result: unknown };
  __revealItemInDir: { args: [target: string]; result: unknown };
  __getFileIcon: { args: [target: string, size?: "small" | "normal" | "large"]; result: string | null };
  __applyBrandAppName: { args: [appName: string | null]; result: { ok: true; appName: string } };
  __applyBrandIcon: { args: [url: string | null]; result: BrandIconApplyResult };
  __getBrandIconState: { args: []; result: BrandIconState };
  __evalRelaunch: { args: []; result: EvalRelaunchResult };
  __getApplicationsForFile: { args: [target: string]; result: { name: string; appPath: string; icon: string | null }[] };
  __openWithApp: { args: [target: string, appPath: string]; result: unknown };
  __fetch: { args: [url: string, init?: DesktopFetchInit]; result: DesktopFetchResult };
  __uploadMultipart: { args: [input: DesktopMultipartUploadInput]; result: DesktopFetchResult };
  __downloadBinary: { args: [input: DesktopBinaryDownloadInput]; result: DesktopBinaryDownloadResult };
  __cancelTransfer: { args: [transferId: string]; result: boolean };
  __homeDir: { args: []; result: string };
  __joinPath: { args: [...segments: string[]]; result: string };
  __setZoomFactor: { args: [factor: number]; result: boolean };
  __setNativeTheme: { args: [theme: string]; result: unknown };
  __setApplicationMenuVisible: { args: [visible: boolean]; result: unknown };
  __setTurnRunning: { args: [running: boolean]; result: unknown };
  __setFinishState: { args: [state: { sessionId: string; kind: "awaiting" | "cut" | null }]; result: unknown };
};

export type DesktopCommandName = keyof DesktopCommandMap;

export type DesktopCommandArgs<C extends DesktopCommandName> = DesktopCommandMap[C]["args"];

export type DesktopCommandResult<C extends DesktopCommandName> = DesktopCommandMap[C]["result"];

/**
 * Main-process handler registry shape. `Event` is electron's
 * IpcMainInvokeEvent (kept generic so this package does not depend on
 * electron types).
 *
 * Args are deliberately loose (`any[]`) on this side: IPC input crosses a
 * trust boundary, so handlers validate/normalize whatever arrives with
 * defensive dynamic access (`String(args[0] ?? "")`, `input.foo ?? null`)
 * rather than assuming the renderer's tuple. `unknown[]` would force ~50
 * narrowing rewrites in the plain-JS main process for no runtime gain.
 * Key parity and result types are still enforced.
 */
type DesktopCommandHandler<Event, C extends DesktopCommandName> = (
  event: Event,
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  ...args: any[]
) => Promise<DesktopCommandResult<C>>;

export type DesktopCommandHandlers<Event = unknown> = {
  [C in Exclude<DesktopCommandName, "__evalRelaunch">]: DesktopCommandHandler<Event, C>;
} & {
  __evalRelaunch?: DesktopCommandHandler<Event, "__evalRelaunch">;
};

/** Renderer-side bridge: one async function per command. */
export type DesktopCommandInvokers = {
  [C in DesktopCommandName]: (...args: DesktopCommandArgs<C>) => Promise<DesktopCommandResult<C>>;
};