// The desktop sidecar's own vocabulary.
//
// These types lived in the PLATFORM's `sidecar/protocol.ts` until the extraction, alongside `vnc:start`
// and `vnc:password` variants in its command and event unions. That is the thing CLAUDE.md warns about
// most plainly — "the platform must not know what your plugin is about. Not just its code, its
// VOCABULARY" — and it is why the platform grew a generic `sendSidecarCommand` instead: it knows a
// command has a type and an id, and nothing else.

export type VncStartParams = {
  email: string;
  username: string;
  resolution?: string;
};

export type VncSessionInfo = {
  email: string;
  display: number;
  port: number;
  pid: number;
  alive: boolean;
};

/** What this plugin sends to its sidecar. `id` is what the reply is matched on. */
export type DesktopCommand =
  // Every sidecar answers this; the connector uses it as a liveness check.
  | { type: 'ping'; id: string }
  | { type: 'vnc:start'; id: string; params: VncStartParams }
  // Provision the password WITHOUT starting a server — the UI needs it before it can open the socket
  // that would start one, so asking `vnc:start` here would be circular.
  | { type: 'vnc:ensure-password'; id: string; email: string }
  | { type: 'vnc:stop'; id: string; email: string };

/** What the sidecar sends back. */
export type DesktopEvent =
  | { type: 'pong'; id: string }
  // The generic failure, for a command this sidecar does not recognise.
  | { type: 'error'; id: string; error: string }
  | { type: 'vnc:started'; id: string; port: number; display: number }
  | { type: 'vnc:password'; id: string; password: string }
  | { type: 'vnc:stopped'; id: string }
  | { type: 'vnc:error'; id: string; error: string };

/** The `handles` key this sidecar registers under, and the one the api addresses it by. */
export const DESKTOP_SIDECAR_KIND = 'vnc';