protocol.ts

/**
 * IDE ↔ Pi protocol types.
 *
 * All messages are newline-delimited JSON (\n terminated) over a Unix domain
 * socket located at <project-root>/.pi/ide/<ide-name>.sock.
 *
 * The IDE name is taken from the socket filename — no in-band handshake is
 * required. Forward compatibility is maintained by adding new opcodes and
 * keeping new fields optional; receivers ignore unknown opcodes.
 */

// ---------------------------------------------------------------------------
// IDE → Pi
// ---------------------------------------------------------------------------

/**
 * Pushed by the IDE whenever the active editor or selection changes
 * (debounced ~200 ms).
 */
export interface IdeContext {
  type: "context";
  /** Path relative to project root.  `null` / omitted when no file is focused. */
  file?: string | null;
  /** 1-indexed inclusive start line of the selection. Omitted when no selection. */
  startLine?: number;
  /** 1-indexed inclusive end line of the selection. Omitted when no selection. */
  endLine?: number;
}

/**
 * Sent by the IDE when the user submits or cancels a review opened via
 * {@link IdeReviewRequest}. At most one review is in flight at a time, so no
 * correlation id is required.
 */
export interface IdeReviewResult {
  type: "reviewResult";
  status: "submitted" | "cancelled";
  /** Empty when cancelled or approved without comments. */
  comments: ReviewComment[];
}

export interface ReviewComment {
  /** Workspace-relative path. */
  file: string;
  /** 1-indexed start line in the post-change file. */
  line: number;
  /** Inclusive end line for multi-line comments. Omitted for single-line. */
  endLine?: number;
  /** User's comment body. */
  text: string;
  /** ±3 lines around the commented line(s) as displayed to the user, with
   *  line numbers and `>` markers preserved. Captured by the IDE so the
   *  agent sees what the user actually saw, even if files change later. */
  context: string[];
}

/** Union of every message the IDE can send to pi. */
export type IdeMessage = IdeContext | IdeReviewResult;

// ---------------------------------------------------------------------------
// Pi → IDE
// ---------------------------------------------------------------------------

/** Asks the IDE to open a review session over a list of files. */
export interface IdeReviewRequest {
  /** Workspace-relative paths to review. */
  files: string[];
}

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

/** Name of the directory under `.pi/` that holds IDE sockets. */
export const IDE_SOCK_DIR = "ide";