pi-x-ide 0.1.0

package/src/pi/commands.ts

@@ -0,0 +1,122 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent" with {
+  "resolution-mode": "import",
+};
+import { formatRangeMention } from "../shared/format";
+import type { LockFileCandidate } from "../shared/protocol";
+import type { PiIdeRuntime } from "./state";
+import { buildWidget, updateIdeUi } from "./ui";
+
+export interface IdeCommandActions {
+  refreshCandidates: (ctx: ExtensionCommandContext) => Promise<LockFileCandidate[]>;
+  connectAuto: (ctx: ExtensionCommandContext) => Promise<void>;
+  connectCandidate: (candidate: LockFileCandidate, ctx: ExtensionCommandContext) => Promise<void>;
+  disconnect: (ctx: ExtensionCommandContext, disabled?: boolean) => void;
+}
+
+export function registerIdeCommand(pi: ExtensionAPI, runtime: PiIdeRuntime, actions: IdeCommandActions): void {
+  pi.registerCommand("ide", {
+    description: "Manage IDE connection and editor selection context",
+    getArgumentCompletions: (argumentPrefix: string) => {
+      const subcommands = [
+        { value: "status", label: "status", description: "Show IDE connection status" },
+        { value: "list", label: "list", description: "List available IDE connections" },
+        { value: "auto", label: "auto", description: "Auto-connect to the most recent IDE" },
+        { value: "off", label: "off", description: "Disable IDE integration" },
+        { value: "attach", label: "attach", description: "Attach latest IDE selection to the prompt" },
+      ];
+      const filtered = subcommands.filter((s) => s.value.startsWith(argumentPrefix));
+      return filtered.length > 0 ? filtered : null;
+    },
+    handler: async (args, ctx) => {
+      runtime.ctx = ctx;
+      const [subcommand] = args.trim().split(/\s+/, 1);
+      switch (subcommand || "") {
+        case "":
+          await showPicker(runtime, actions, ctx);
+          return;
+        case "status":
+          showStatus(runtime, ctx);
+          return;
+        case "list":
+          await listCandidates(actions, ctx);
+          return;
+        case "auto":
+          runtime.enabled = true;
+          await actions.connectAuto(ctx);
+          return;
+        case "off":
+          actions.disconnect(ctx, true);
+          return;
+        case "attach":
+          attachLatest(runtime, ctx);
+          return;
+        default:
+          ctx.ui.notify("Usage: /ide [status|list|auto|off|attach]", "warning");
+      }
+    },
+  });
+}
+
+async function showPicker(
+  runtime: PiIdeRuntime,
+  actions: IdeCommandActions,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  const candidates = await actions.refreshCandidates(ctx);
+  if (candidates.length === 0) {
+    ctx.ui.notify("No matching IDE connections found.", "warning");
+    return;
+  }
+
+  const labels = candidates.map(
+    (candidate, index) => `${index + 1}. ${candidate.lock.name} — ${candidate.workspaceFolder}`,
+  );
+  labels.push("Disable IDE integration");
+  const choice = await ctx.ui.select("Select IDE connection", labels);
+  if (!choice) return;
+  if (choice === "Disable IDE integration") {
+    actions.disconnect(ctx, true);
+    return;
+  }
+
+  const index = labels.indexOf(choice);
+  const candidate = candidates[index];
+  if (candidate) {
+    runtime.enabled = true;
+    await actions.connectCandidate(candidate, ctx);
+  }
+}
+
+function showStatus(runtime: PiIdeRuntime, ctx: ExtensionCommandContext): void {
+  const lines = buildWidget(runtime, ctx.cwd) ?? ["IDE: disconnected"];
+  ctx.ui.notify(lines.join("\n"), runtime.connectionStatus === "error" ? "error" : "info");
+}
+
+async function listCandidates(actions: IdeCommandActions, ctx: ExtensionCommandContext): Promise<void> {
+  const candidates = await actions.refreshCandidates(ctx);
+  if (candidates.length === 0) {
+    ctx.ui.notify("No matching IDE lock files found.", "info");
+    return;
+  }
+  ctx.ui.notify(
+    candidates
+      .map(
+        (candidate, index) =>
+          `${index + 1}. ${candidate.lock.name} ${candidate.lock.host}:${candidate.lock.port}\n   ${candidate.workspaceFolder}\n   ${candidate.path}`,
+      )
+      .join("\n"),
+    "info",
+  );
+}
+
+function attachLatest(runtime: PiIdeRuntime, ctx: ExtensionCommandContext): void {
+  if (!runtime.latestSelection) {
+    ctx.ui.notify("No IDE selection is available.", "warning");
+    return;
+  }
+  const mention = formatRangeMention(runtime.latestSelection, { cwd: ctx.cwd });
+  ctx.ui.pasteToEditor(mention);
+  runtime.attachState = "pending";
+  updateIdeUi(runtime, ctx);
+  ctx.ui.notify(`Attached ${mention}`, "info");
+}

package/src/pi/connection.ts

@@ -0,0 +1,155 @@
+import WebSocket from "ws";
+import {
+  AUTH_HEADER,
+  PROTOCOL_VERSION,
+  type AtMentionedParams,
+  type EditorSelectionSnapshot,
+  type JsonRpcResponse,
+  type LockFileCandidate,
+  type SelectionChangedParams,
+  type SelectionClearedParams,
+} from "../shared/protocol";
+import { isAtMentionedParams, isSelectionChangedParams, isSelectionClearedParams } from "../shared/schema";
+import { decodeRawData } from "../shared/ws";
+
+export interface IdeConnectionCallbacks {
+  onConnected?: (server: { name: string; version?: string; ide?: string }) => void;
+  onDisconnected?: (reason: string) => void;
+  onSelectionChanged?: (snapshot: EditorSelectionSnapshot) => void;
+  onSelectionCleared?: (params: SelectionClearedParams) => void;
+  onAtMentioned?: (params: AtMentionedParams) => void;
+  onError?: (error: Error) => void;
+}
+
+export class IdeConnection {
+  private socket?: WebSocket;
+  private nextId = 1;
+  private closedByUser = false;
+
+  constructor(
+    readonly candidate: LockFileCandidate,
+    private readonly cwd: string,
+    private readonly callbacks: IdeConnectionCallbacks,
+  ) {}
+
+  get isOpen(): boolean {
+    return this.socket?.readyState === WebSocket.OPEN;
+  }
+
+  async connect(): Promise<void> {
+    this.closedByUser = false;
+    const { lock } = this.candidate;
+    const socket = new WebSocket(`ws://${lock.host}:${lock.port}`, {
+      headers: {
+        [AUTH_HEADER]: lock.authToken,
+      },
+    });
+    this.socket = socket;
+
+    socket.on("message", (raw) => this.handleMessage(decodeRawData(raw)));
+    socket.on("close", (_code, reason) => {
+      if (this.socket === socket) this.socket = undefined;
+      this.callbacks.onDisconnected?.(reason.toString("utf8") || (this.closedByUser ? "closed" : "disconnected"));
+    });
+    socket.on("error", (error) => this.callbacks.onError?.(error));
+
+    await new Promise<void>((resolve, reject) => {
+      const onOpen = () => {
+        cleanup();
+        this.sendInitialize();
+        resolve();
+      };
+      const onError = (error: Error) => {
+        cleanup();
+        reject(error);
+      };
+      const cleanup = () => {
+        socket.off("open", onOpen);
+        socket.off("error", onError);
+      };
+      socket.once("open", onOpen);
+      socket.once("error", onError);
+    });
+  }
+
+  disconnect(): void {
+    this.closedByUser = true;
+    this.socket?.close();
+    this.socket = undefined;
+  }
+
+  private sendInitialize(): void {
+    this.socket?.send(
+      JSON.stringify({
+        jsonrpc: "2.0",
+        id: this.nextId++,
+        method: "initialize",
+        params: {
+          protocolVersion: PROTOCOL_VERSION,
+          client: { name: "pi-x-ide", version: "0.1.0" },
+          cwd: this.cwd,
+        },
+      }),
+    );
+  }
+
+  private handleMessage(text: string): void {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text) as unknown;
+    } catch {
+      return;
+    }
+
+    if (isRpcResponse(parsed)) {
+      const server = getServerInfo(parsed);
+      if (server) this.callbacks.onConnected?.(server);
+      return;
+    }
+
+    if (!isNotification(parsed)) return;
+    if (parsed.method === "selection_changed" && isSelectionChangedParams(parsed.params)) {
+      this.callbacks.onSelectionChanged?.(withReceivedAt(parsed.params));
+    } else if (parsed.method === "selection_cleared" && isSelectionClearedParams(parsed.params)) {
+      this.callbacks.onSelectionCleared?.(withReceivedAt(parsed.params));
+    } else if (parsed.method === "at_mentioned" && isAtMentionedParams(parsed.params)) {
+      const params = withReceivedAt(parsed.params);
+      this.callbacks.onAtMentioned?.(params);
+    }
+  }
+}
+
+function withReceivedAt<T extends SelectionChangedParams | SelectionClearedParams>(params: T): T {
+  return { ...params, receivedAt: params.receivedAt ?? Date.now() };
+}
+
+function isNotification(value: unknown): value is { jsonrpc: "2.0"; method: string; params?: unknown } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { jsonrpc?: unknown }).jsonrpc === "2.0" &&
+    typeof (value as { method?: unknown }).method === "string"
+  );
+}
+
+function isRpcResponse(value: unknown): value is JsonRpcResponse {
+  return (
+    typeof value === "object" && value !== null && (value as { jsonrpc?: unknown }).jsonrpc === "2.0" && "id" in value
+  );
+}
+
+function getServerInfo(response: JsonRpcResponse): { name: string; version?: string; ide?: string } | undefined {
+  const result = response.result;
+  if (!result || typeof result !== "object") return undefined;
+  const server = (result as { server?: unknown }).server;
+  if (!server || typeof server !== "object") return undefined;
+  const name = (server as { name?: unknown }).name;
+  if (typeof name !== "string") return undefined;
+  const version = (server as { version?: unknown }).version;
+  const ide = (server as { ide?: unknown }).ide;
+  return {
+    name,
+    version: typeof version === "string" ? version : undefined,
+    ide: typeof ide === "string" ? ide : undefined,
+  };
+}

package/src/pi/context.ts

@@ -0,0 +1,82 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent" with {
+  "resolution-mode": "import",
+};
+import { formatEditorContext, snapshotKey } from "../shared/format";
+import type { EditorSelectionSnapshot } from "../shared/protocol";
+import type { PiIdeRuntime } from "./state";
+import { updateIdeUi } from "./ui";
+
+const CONTEXT_MARKER = "pi-x-ide/editor-context";
+
+export function registerContextHandlers(pi: ExtensionAPI, runtime: PiIdeRuntime): void {
+  pi.on("before_agent_start", (_event, ctx) => {
+    runtime.ctx = ctx;
+    if (!runtime.enabled) return;
+    if (!runtime.latestSelection) return;
+    if (runtime.attachState !== "pending") return;
+
+    runtime.turnSelection = runtime.latestSelection;
+  });
+
+  // Merge the active editor context into the submitted user prompt rather than
+  // adding a separate extension message.
+  pi.on("message_end", (event, ctx) => {
+    runtime.ctx = ctx;
+    if (!runtime.enabled || !runtime.turnSelection) return;
+    if (event.message.role !== "user") return;
+    if (messageContainsMarker(event.message)) return;
+
+    const text = `${formatEditorContext(runtime.turnSelection, { cwd: ctx.cwd })}\n<!-- ${CONTEXT_MARKER} -->\n`;
+    const message = mergeIntoUserMessage(event.message, text);
+    runtime.attachState = "sent";
+    runtime.turnSelection = undefined;
+    updateIdeUi(runtime, ctx);
+    return { message };
+  });
+}
+
+export function setLatestSelection(
+  runtime: PiIdeRuntime,
+  snapshot: EditorSelectionSnapshot,
+  ctx?: ExtensionContext,
+): void {
+  const key = snapshotKey(snapshot);
+  runtime.latestSelection = snapshot;
+  if (runtime.latestSelectionKey !== key) {
+    runtime.latestSelectionKey = key;
+    runtime.attachState = "pending";
+  }
+  updateIdeUi(runtime, ctx);
+}
+
+export function clearLatestSelection(runtime: PiIdeRuntime, ctx?: ExtensionContext): void {
+  runtime.latestSelection = undefined;
+  runtime.latestSelectionKey = undefined;
+  runtime.turnSelection = undefined;
+  runtime.attachState = "idle";
+  updateIdeUi(runtime, ctx);
+}
+
+type UserContentBlock =
+  | { type: "text"; text: string; textSignature?: string }
+  | { type: "image"; data: string; mimeType: string };
+
+type MergeableUserMessage = {
+  role: "user";
+  content: string | UserContentBlock[];
+};
+
+function mergeIntoUserMessage<T extends MergeableUserMessage>(message: T, text: string): T {
+  return {
+    ...message,
+    content: [{ type: "text", text }, ...normalizeUserContent(message.content)],
+  };
+}
+
+function normalizeUserContent(content: MergeableUserMessage["content"]): UserContentBlock[] {
+  return typeof content === "string" ? [{ type: "text", text: content }] : content;
+}
+
+function messageContainsMarker(message: MergeableUserMessage): boolean {
+  return JSON.stringify(message).includes(CONTEXT_MARKER);
+}

package/src/pi/discovery.ts

@@ -0,0 +1,88 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { LOCK_FILE_EXTENSION, type IdeLockFile, type LockFileCandidate } from "../shared/protocol";
+import { relationshipMatchLength, resolveLockDir } from "../shared/paths";
+import { parseLockFileContent } from "../shared/schema";
+
+export interface DiscoverOptions {
+  cwd: string;
+  lockDir?: string;
+  now?: number;
+  maxAgeMs?: number;
+  checkPid?: boolean;
+}
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function bestWorkspaceMatch(
+  lock: IdeLockFile,
+  cwd: string,
+): { matchLength: number; workspaceFolder: string } | undefined {
+  let best: { matchLength: number; workspaceFolder: string } | undefined;
+  for (const workspaceFolder of lock.workspaceFolders) {
+    const matchLength = relationshipMatchLength(workspaceFolder, cwd);
+    if (matchLength <= 0) continue;
+    if (!best || matchLength > best.matchLength) {
+      best = { matchLength, workspaceFolder };
+    }
+  }
+  return best;
+}
+
+export function sortCandidates(candidates: LockFileCandidate[]): LockFileCandidate[] {
+  return [...candidates].sort(
+    (a, b) => b.matchLength - a.matchLength || b.mtimeMs - a.mtimeMs || a.path.localeCompare(b.path),
+  );
+}
+
+export async function discoverIdeCandidates(options: DiscoverOptions): Promise<LockFileCandidate[]> {
+  const lockDir = options.lockDir ?? resolveLockDir();
+  const now = options.now ?? Date.now();
+  const maxAgeMs = options.maxAgeMs ?? 24 * 60 * 60 * 1000;
+  const checkPid = options.checkPid ?? true;
+
+  let entries: string[];
+  try {
+    entries = await readdir(lockDir);
+  } catch {
+    return [];
+  }
+
+  const candidates: LockFileCandidate[] = [];
+  for (const entry of entries) {
+    if (!entry.endsWith(LOCK_FILE_EXTENSION)) continue;
+    const path = join(lockDir, entry);
+    let content: string;
+    let mtimeMs: number;
+    try {
+      const [fileContent, fileStat] = await Promise.all([readFile(path, "utf8"), stat(path)]);
+      content = fileContent;
+      mtimeMs = fileStat.mtimeMs;
+    } catch {
+      continue;
+    }
+
+    if (now - mtimeMs > maxAgeMs) continue;
+    const lock = parseLockFileContent(content);
+    if (!lock) continue;
+    if (checkPid && typeof lock.pid === "number" && !isProcessAlive(lock.pid)) continue;
+
+    const match = bestWorkspaceMatch(lock, options.cwd);
+    if (!match) continue;
+
+    candidates.push({ path, lock, mtimeMs, ...match });
+  }
+
+  return sortCandidates(candidates);
+}
+
+export async function resolveBestIdeCandidate(options: DiscoverOptions): Promise<LockFileCandidate | undefined> {
+  return (await discoverIdeCandidates(options))[0];
+}

package/src/pi/index.ts

@@ -0,0 +1,190 @@
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent" with {
+  "resolution-mode": "import",
+};
+import { formatRangeMention } from "../shared/format";
+import type { AtMentionedParams, LockFileCandidate } from "../shared/protocol";
+import { discoverIdeCandidates } from "./discovery";
+import { IdeConnection } from "./connection";
+import { registerIdeCommand } from "./commands";
+import { clearLatestSelection, registerContextHandlers, setLatestSelection } from "./context";
+import { createRuntime, type PiIdeRuntime } from "./state";
+import { clearIdeUi, updateIdeUi } from "./ui";
+
+const RECONNECT_DELAY_MS = 2_000;
+
+export default function (pi: ExtensionAPI): void {
+  const runtime = createRuntime();
+
+  registerContextHandlers(pi, runtime);
+  registerIdeCommand(pi, runtime, {
+    refreshCandidates: (ctx) => refreshCandidates(runtime, ctx),
+    connectAuto: (ctx) => connectAuto(runtime, ctx),
+    connectCandidate: (candidate, ctx) => connectCandidate(runtime, candidate, ctx),
+    disconnect: (ctx, disabled) => disconnect(runtime, ctx, disabled),
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    runtime.ctx = ctx;
+    runtime.cwd = ctx.cwd;
+    if (!runtime.enabled) {
+      runtime.connectionStatus = "disabled";
+      updateIdeUi(runtime, ctx);
+      return;
+    }
+    await connectAuto(runtime, ctx);
+  });
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    runtime.ctx = ctx;
+    if (runtime.reconnectTimer) clearTimeout(runtime.reconnectTimer);
+    runtime.reconnectTimer = undefined;
+    runtime.connection?.disconnect();
+    runtime.connection = undefined;
+    clearIdeUi(runtime, ctx);
+  });
+}
+
+async function refreshCandidates(
+  runtime: PiIdeRuntime,
+  ctx: ExtensionContext | ExtensionCommandContext,
+): Promise<LockFileCandidate[]> {
+  runtime.ctx = ctx;
+  runtime.cwd = ctx.cwd;
+  runtime.candidates = await discoverIdeCandidates({ cwd: ctx.cwd });
+  return runtime.candidates;
+}
+
+async function connectAuto(runtime: PiIdeRuntime, ctx: ExtensionContext | ExtensionCommandContext): Promise<void> {
+  runtime.enabled = true;
+  const candidates = await refreshCandidates(runtime, ctx);
+  const candidate = candidates[0];
+  if (!candidate) {
+    runtime.connectionStatus = "disconnected";
+    runtime.connectionMessage = "No matching IDE lock files found.";
+    runtime.currentCandidate = undefined;
+    runtime.connectedServer = undefined;
+    updateIdeUi(runtime, ctx);
+    return;
+  }
+  await connectCandidate(runtime, candidate, ctx);
+}
+
+async function connectCandidate(
+  runtime: PiIdeRuntime,
+  candidate: LockFileCandidate,
+  ctx: ExtensionContext | ExtensionCommandContext,
+): Promise<void> {
+  runtime.ctx = ctx;
+  runtime.cwd = ctx.cwd;
+  runtime.enabled = true;
+  if (runtime.reconnectTimer) clearTimeout(runtime.reconnectTimer);
+  runtime.reconnectTimer = undefined;
+
+  const previous = runtime.connection;
+  runtime.connection = undefined;
+  previous?.disconnect();
+
+  runtime.currentCandidate = candidate;
+  runtime.connectedServer = undefined;
+  runtime.connectionStatus = "connecting";
+  runtime.connectionMessage = `Connecting to ${candidate.lock.name} at ${candidate.lock.host}:${candidate.lock.port}`;
+  updateIdeUi(runtime, ctx);
+
+  const connection = new IdeConnection(candidate, ctx.cwd, {
+    onConnected: (server) => {
+      if (runtime.connection !== connection) return;
+      runtime.connectedServer = server;
+      runtime.connectionStatus = "connected";
+      runtime.connectionMessage = undefined;
+      updateIdeUi(runtime);
+    },
+    onDisconnected: (reason) => {
+      if (runtime.connection !== connection) return;
+      runtime.connection = undefined;
+      runtime.connectedServer = undefined;
+      runtime.connectionStatus = runtime.enabled ? "disconnected" : "disabled";
+      runtime.connectionMessage = reason;
+      updateIdeUi(runtime);
+      if (runtime.enabled) scheduleReconnect(runtime);
+    },
+    onSelectionChanged: (snapshot) => {
+      if (runtime.connection !== connection) return;
+      setLatestSelection(runtime, snapshot);
+    },
+    onSelectionCleared: () => {
+      if (runtime.connection !== connection) return;
+      clearLatestSelection(runtime);
+    },
+    onAtMentioned: (params) => {
+      if (runtime.connection !== connection) return;
+      handleAtMentioned(runtime, params);
+    },
+    onError: (error) => {
+      if (runtime.connection !== connection) return;
+      runtime.connectionStatus = "error";
+      runtime.connectionMessage = error.message;
+      updateIdeUi(runtime);
+    },
+  });
+
+  runtime.connection = connection;
+  try {
+    await connection.connect();
+    if (runtime.connection === connection && runtime.connectionStatus === "connecting") {
+      runtime.connectionStatus = "connected";
+      runtime.connectionMessage = undefined;
+      updateIdeUi(runtime, ctx);
+    }
+  } catch (error) {
+    if (runtime.connection === connection) {
+      runtime.connection = undefined;
+      runtime.connectionStatus = "error";
+      runtime.connectionMessage = error instanceof Error ? error.message : String(error);
+      updateIdeUi(runtime, ctx);
+      scheduleReconnect(runtime);
+    }
+  }
+}
+
+function disconnect(runtime: PiIdeRuntime, ctx: ExtensionContext | ExtensionCommandContext, disabled = false): void {
+  runtime.ctx = ctx;
+  if (runtime.reconnectTimer) clearTimeout(runtime.reconnectTimer);
+  runtime.reconnectTimer = undefined;
+  const connection = runtime.connection;
+  runtime.connection = undefined;
+  connection?.disconnect();
+  runtime.enabled = !disabled;
+  runtime.connectedServer = undefined;
+  runtime.connectionStatus = disabled ? "disabled" : "disconnected";
+  runtime.connectionMessage = disabled ? "IDE integration disabled." : "Disconnected.";
+  if (disabled) {
+    runtime.latestSelection = undefined;
+    runtime.latestSelectionKey = undefined;
+    runtime.turnSelection = undefined;
+    runtime.attachState = "idle";
+  }
+  updateIdeUi(runtime, ctx);
+}
+
+function scheduleReconnect(runtime: PiIdeRuntime): void {
+  if (runtime.reconnectTimer || !runtime.enabled) return;
+  runtime.reconnectTimer = setTimeout(() => {
+    runtime.reconnectTimer = undefined;
+    const ctx = runtime.ctx;
+    if (!ctx || !runtime.enabled) return;
+    connectAuto(runtime, ctx).catch((error: unknown) => {
+      runtime.connectionStatus = "error";
+      runtime.connectionMessage = error instanceof Error ? error.message : String(error);
+      updateIdeUi(runtime);
+    });
+  }, RECONNECT_DELAY_MS);
+}
+
+function handleAtMentioned(runtime: PiIdeRuntime, params: AtMentionedParams): void {
+  setLatestSelection(runtime, params);
+  const ctx = runtime.ctx;
+  if (!ctx?.hasUI) return;
+  const text = params.rangeText || formatRangeMention(params, { cwd: ctx.cwd });
+  ctx.ui.pasteToEditor(text);
+  ctx.ui.notify(`Attached ${text}`, "info");
+}

package/src/pi/state.ts

@@ -0,0 +1,29 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent" with { "resolution-mode": "import" };
+import type { AttachState, EditorSelectionSnapshot, LockFileCandidate } from "../shared/protocol";
+import type { IdeConnection } from "./connection";
+
+export interface PiIdeRuntime {
+  ctx?: ExtensionContext;
+  cwd?: string;
+  enabled: boolean;
+  connection?: IdeConnection;
+  currentCandidate?: LockFileCandidate;
+  candidates: LockFileCandidate[];
+  connectedServer?: { name: string; version?: string; ide?: string };
+  connectionStatus: "idle" | "connecting" | "connected" | "disconnected" | "error" | "disabled";
+  connectionMessage?: string;
+  latestSelection?: EditorSelectionSnapshot;
+  latestSelectionKey?: string;
+  attachState: AttachState;
+  turnSelection?: EditorSelectionSnapshot;
+  reconnectTimer?: NodeJS.Timeout;
+}
+
+export function createRuntime(): PiIdeRuntime {
+  return {
+    enabled: true,
+    candidates: [],
+    connectionStatus: "idle",
+    attachState: "idle",
+  };
+}