tmux-ide 2.6.1 → 2.8.0

package/packages/daemon/src/control/client.ts

@@ -0,0 +1,128 @@
+/**
+ * A minimal control-socket client — what the CLI's `--socket` fast-paths
+ * (`events --follow --socket`, `wait … --socket`) ride on. Connect, send
+ * id-correlated requests, optionally receive pushed event frames. Kept
+ * dependency-light on purpose: this is also the reference for "how would an
+ * agent drive the socket from node" (see skill/SKILL.md).
+ */
+import { connect, type Socket } from "node:net";
+import {
+  CONTROL_PROTOCOL_VERSION,
+  controlEventSchema,
+  controlResponseSchema,
+  type ControlEventFrame,
+} from "@tmux-ide/contracts";
+import { createFrameSplitter, encodeFrame } from "./frames.ts";
+import { defaultControlSocketPath } from "./server.ts";
+
+/** A failed verb, carrying the server's machine-readable error code. */
+export class ControlRequestError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
+export interface ControlClient {
+  /** Send one verb; resolves with the response `data`, rejects with
+   *  {@link ControlRequestError} on an error response or a dropped socket. */
+  request(verb: string, params?: Record<string, unknown>): Promise<unknown>;
+  /** Receive pushed event frames (also sends the `subscribe` verb). */
+  subscribe(onEvent: (event: ControlEventFrame) => void): Promise<void>;
+  close(): void;
+  /** Resolves when the connection ends (server shutdown → EOF). */
+  done: Promise<void>;
+}
+
+/**
+ * Connect to a control server. Rejects (quickly) when nothing is listening —
+ * callers treat that as "no server, fall back to polling".
+ */
+export function connectControl(opts: { socketPath?: string } = {}): Promise<ControlClient> {
+  const path = opts.socketPath ?? defaultControlSocketPath();
+  return new Promise((resolve, reject) => {
+    const socket: Socket = connect(path);
+    socket.once("error", reject);
+    socket.once("connect", () => {
+      socket.removeListener("error", reject);
+      resolve(wrap(socket));
+    });
+  });
+}
+
+function wrap(socket: Socket): ControlClient {
+  socket.setEncoding("utf8");
+  const split = createFrameSplitter();
+  const pending = new Map<
+    string | number,
+    { resolve: (data: unknown) => void; reject: (err: Error) => void }
+  >();
+  const eventSinks: Array<(event: ControlEventFrame) => void> = [];
+  let nextId = 1;
+
+  let markDone: () => void;
+  const done = new Promise<void>((r) => {
+    markDone = r;
+  });
+
+  socket.on("data", (chunk: string) => {
+    for (const line of split(chunk)) {
+      let raw: unknown;
+      try {
+        raw = JSON.parse(line);
+      } catch {
+        continue; // a malformed server frame — skip, ids keep us honest
+      }
+      const event = controlEventSchema.safeParse(raw);
+      if (event.success) {
+        for (const sink of eventSinks) sink(event.data);
+        continue;
+      }
+      const response = controlResponseSchema.safeParse(raw);
+      if (!response.success || response.data.id === null) continue;
+      const waiter = pending.get(response.data.id);
+      if (!waiter) continue;
+      pending.delete(response.data.id);
+      if (response.data.ok) waiter.resolve(response.data.data);
+      else {
+        waiter.reject(
+          new ControlRequestError(response.data.error.code, response.data.error.message),
+        );
+      }
+    }
+  });
+  const teardown = (): void => {
+    for (const { reject } of pending.values()) {
+      reject(new ControlRequestError("disconnected", "control socket closed"));
+    }
+    pending.clear();
+    markDone();
+  };
+  socket.on("close", teardown);
+  socket.on("error", () => {
+    // 'close' follows and runs the teardown
+  });
+
+  const request = (verb: string, params?: Record<string, unknown>): Promise<unknown> => {
+    const id = nextId++;
+    return new Promise((resolve, reject) => {
+      if (socket.destroyed) {
+        reject(new ControlRequestError("disconnected", "control socket closed"));
+        return;
+      }
+      pending.set(id, { resolve, reject });
+      socket.write(encodeFrame({ v: CONTROL_PROTOCOL_VERSION, id, verb, params }));
+    });
+  };
+
+  return {
+    request,
+    subscribe: async (onEvent) => {
+      eventSinks.push(onEvent);
+      await request("subscribe");
+    },
+    close: () => socket.destroy(),
+    done,
+  };
+}

package/packages/daemon/src/control/dispatch.ts

@@ -0,0 +1,107 @@
+/**
+ * Request dispatch for the control socket — PURE given its handler map.
+ *
+ * Takes one raw frame line, parses + validates the versioned envelope,
+ * routes to the verb's handler, and shapes the response envelope — including
+ * every failure mode (unparseable JSON, bad envelope, unknown verb, invalid
+ * params, handler error). Handlers are injected, so this whole layer unit-
+ * tests without a socket or a tmux server.
+ *
+ * Error codes on the wire:
+ *   bad-request    unparseable frame / envelope / params (message says which)
+ *   unknown-verb   the verb isn't in this server's handler map
+ *   not-found      the named pane/session/target doesn't exist
+ *   timeout        a `wait` ran out of time
+ *   internal       the handler threw something unexpected
+ */
+import {
+  CONTROL_PROTOCOL_VERSION,
+  controlRequestSchema,
+  type ControlResponse,
+} from "@tmux-ide/contracts";
+import { IdeError } from "../lib/errors.ts";
+
+/** Thrown by handlers to reach the wire with a specific code. */
+export class ControlVerbError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
+/** What a handler gets besides its (already unknown-typed) params. */
+export interface VerbContext {
+  /** Flip this connection into receiving event frames (the `subscribe` verb). */
+  subscribe: () => void;
+}
+
+export type VerbHandler = (params: unknown, ctx: VerbContext) => Promise<unknown> | unknown;
+
+const ok = (id: string | number, data: unknown): ControlResponse => ({
+  v: CONTROL_PROTOCOL_VERSION,
+  id,
+  ok: true,
+  data,
+});
+
+const fail = (id: string | number | null, code: string, message: string): ControlResponse => ({
+  v: CONTROL_PROTOCOL_VERSION,
+  id,
+  ok: false,
+  error: { code, message },
+});
+
+/** Best-effort id recovery from a frame that failed envelope validation. */
+function extractId(value: unknown): string | number | null {
+  if (typeof value === "object" && value !== null && "id" in value) {
+    const id = (value as { id: unknown }).id;
+    if (typeof id === "string" || typeof id === "number") return id;
+  }
+  return null;
+}
+
+/**
+ * Dispatch one raw line to `handlers`. ALWAYS resolves to a response frame —
+ * a protocol error is an answer, never a dropped request or a thrown error
+ * (only the transport decides to drop connections).
+ */
+export async function dispatchLine(
+  line: string,
+  handlers: Record<string, VerbHandler>,
+  ctx: VerbContext,
+): Promise<ControlResponse> {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(line);
+  } catch {
+    return fail(null, "bad-request", "frame is not valid JSON");
+  }
+
+  const parsed = controlRequestSchema.safeParse(raw);
+  if (!parsed.success) {
+    return fail(
+      extractId(raw),
+      "bad-request",
+      `invalid request envelope (need {v:${CONTROL_PROTOCOL_VERSION}, id, verb})`,
+    );
+  }
+
+  const { id, verb, params } = parsed.data;
+  const handler = handlers[verb];
+  if (!handler) {
+    return fail(id, "unknown-verb", `unknown verb "${verb}"`);
+  }
+
+  try {
+    return ok(id, await handler(params ?? {}, ctx));
+  } catch (err) {
+    if (err instanceof ControlVerbError) return fail(id, err.code, err.message);
+    if (err instanceof IdeError) {
+      // Data-layer errors carry honest codes already (SESSION_NOT_FOUND, …).
+      const code = err.code === "USAGE" ? "bad-request" : "not-found";
+      return fail(id, code, err.message);
+    }
+    return fail(id, "internal", (err as Error)?.message ?? "internal error");
+  }
+}

package/packages/daemon/src/control/fanout.ts

@@ -0,0 +1,44 @@
+/**
+ * Subscriber fan-out bookkeeping for the control server — PURE.
+ *
+ * Tracks the set of live subscribers and delivers each emitted event to all
+ * of them. The `onFirst`/`onLast` edges let the server run its detection
+ * tick ONLY while someone is listening (0→1 starts it, 1→0 stops it), so an
+ * idle `tmux-ide serve` costs nothing between requests.
+ */
+
+export interface Fanout<T> {
+  /** Register a sink. Returns its unsubscribe (idempotent). */
+  add(sink: (event: T) => void): () => void;
+  /** Deliver `event` to every sink. A throwing sink is dropped, not fatal. */
+  emit(event: T): void;
+  size(): number;
+}
+
+export function createFanout<T>(
+  edges: { onFirst?: () => void; onLast?: () => void } = {},
+): Fanout<T> {
+  const sinks = new Set<(event: T) => void>();
+  const remove = (sink: (event: T) => void): void => {
+    if (!sinks.delete(sink)) return;
+    if (sinks.size === 0) edges.onLast?.();
+  };
+  return {
+    add(sink) {
+      sinks.add(sink);
+      if (sinks.size === 1) edges.onFirst?.();
+      return () => remove(sink);
+    },
+    emit(event) {
+      for (const sink of [...sinks]) {
+        try {
+          sink(event);
+        } catch {
+          // A sink that throws (a torn-down connection) removes itself.
+          remove(sink);
+        }
+      }
+    },
+    size: () => sinks.size,
+  };
+}

package/packages/daemon/src/control/frames.ts

@@ -0,0 +1,40 @@
+/**
+ * NDJSON framing for the control socket — PURE.
+ *
+ * One frame = one JSON object on one `\n`-terminated line. TCP-style streams
+ * deliver arbitrary chunk boundaries, so the splitter buffers a partial
+ * trailing line across feeds and hands back only COMPLETE lines. Encoding is
+ * the trivial inverse; it lives here so every writer produces identical
+ * frames (a `JSON.stringify` can never contain a raw newline, so one write
+ * call per frame is atomic on the wire).
+ */
+
+/** Refuse to buffer a partial line beyond this — a client streaming an
+ *  unterminated megabyte is broken or hostile, not slow. */
+export const MAX_FRAME_BYTES = 4 * 1024 * 1024;
+
+/** Serialize one frame: the JSON line plus its terminator. */
+export function encodeFrame(message: unknown): string {
+  return `${JSON.stringify(message)}\n`;
+}
+
+/**
+ * A stateful chunk → complete-lines splitter. Feed it raw socket data; it
+ * returns every COMPLETE line received so far (blank lines are dropped) and
+ * keeps the trailing partial line buffered for the next feed. Throws when the
+ * partial line outgrows {@link MAX_FRAME_BYTES} — the caller should drop the
+ * connection.
+ */
+export function createFrameSplitter(): (chunk: string) => string[] {
+  let buffer = "";
+  return (chunk: string): string[] => {
+    buffer += chunk;
+    const parts = buffer.split("\n");
+    buffer = parts.pop() ?? "";
+    if (buffer.length > MAX_FRAME_BYTES) {
+      buffer = "";
+      throw new Error(`frame exceeds ${MAX_FRAME_BYTES} bytes without a newline`);
+    }
+    return parts.filter((line) => line.trim().length > 0);
+  };
+}

package/packages/daemon/src/control/lifecycle.ts

@@ -0,0 +1,151 @@
+/**
+ * Agent lifecycle io for the control socket — spawn / restart / stop.
+ *
+ * The MODEL (kind → launch command, exact tmux argv, the shell-vs-own-process
+ * restart decision, interrupt timing) is the pure `tui/mirror/agent-lifecycle`
+ * module the unified app already runs on; this file is only the async tmux
+ * plumbing around it, so the socket drives the SAME lifecycle path as the app.
+ */
+import { execFile } from "node:child_process";
+import {
+  INTERRUPT_TAP_GAP_MS,
+  RESTART_GRACE_MS,
+  clearAuthorityArgs,
+  interruptArgs,
+  launchCommandFor,
+  paneHostsShell,
+  relaunchArgs,
+  respawnArgs,
+  spawnAgentArgs,
+  spawnSessionArgs,
+  type SpawnPlacement,
+} from "../tui/mirror/agent-lifecycle.ts";
+import { getManifests } from "../tui/detect/manifest-loader.ts";
+import { ControlVerbError } from "./dispatch.ts";
+
+const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+/** One tmux call; resolves stdout, rejects on a tmux error. */
+function tmuxRun(args: string[]): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile("tmux", args, (err, stdout) => (err ? reject(err) : resolve(stdout.trimEnd())));
+  });
+}
+
+/** Like {@link tmuxRun} but errors are swallowed — for best-effort steps
+ *  (a dead pane target is a normal race, the fleet shows the truth later). */
+async function tmuxTry(args: string[]): Promise<void> {
+  await tmuxRun(args).catch(() => {});
+}
+
+/** Resolve `kind`/`command` params to the command that actually launches. */
+export function resolveLaunchCommand(params: { kind?: string; command?: string }): string {
+  if (params.command) return params.command;
+  return launchCommandFor(params.kind!, getManifests());
+}
+
+export interface SpawnOutcome {
+  paneId: string;
+  session: string;
+  command: string;
+  placement: SpawnPlacement | "new-session";
+}
+
+/**
+ * Spawn an agent. With `session` the shared placement argv is used (window /
+ * split); without it a fresh detached session named `sessionName` starts in
+ * `dir`. `-P -F #{pane_id}` is threaded right after the tmux subcommand so
+ * the caller learns WHICH pane the agent got (the argv builders stay
+ * untouched — the app's flows don't want the print).
+ */
+export async function spawnAgent(params: {
+  command: string;
+  session?: string;
+  sessionName?: string;
+  dir?: string;
+  placement?: SpawnPlacement;
+  paneId?: string;
+}): Promise<SpawnOutcome> {
+  const dir = params.dir ?? null;
+  const argv = params.session
+    ? spawnAgentArgs(
+        params.placement ?? "window",
+        { session: params.session, paneId: params.paneId },
+        dir,
+        params.command,
+      )
+    : spawnSessionArgs(params.sessionName!, dir, params.command);
+  const [subcommand, ...rest] = argv;
+  let paneId: string;
+  try {
+    paneId = await tmuxRun([subcommand!, "-P", "-F", "#{pane_id}", ...rest]);
+  } catch (err) {
+    throw new ControlVerbError("not-found", `tmux refused to spawn: ${(err as Error).message}`);
+  }
+  const session = params.session ?? params.sessionName!;
+  // Mark a fresh session as ours (mirrors the app's spawn flow).
+  if (!params.session) await tmuxTry(["set-environment", "-t", session, "TMUX_IDE", "1"]);
+  return {
+    paneId,
+    session,
+    command: params.command,
+    placement: params.session ? (params.placement ?? "window") : "new-session",
+  };
+}
+
+/** The double ctrl-c (see agent-lifecycle: one taps, the quick second exits). */
+async function interruptAgent(paneId: string): Promise<void> {
+  await tmuxTry(interruptArgs(paneId));
+  await sleep(INTERRUPT_TAP_GAP_MS);
+  await tmuxTry(interruptArgs(paneId));
+}
+
+/** Out-of-band stop hygiene: no hook fires, so unset the authority stamps. */
+async function clearAgentAuthority(paneId: string): Promise<void> {
+  for (const args of clearAuthorityArgs(paneId)) await tmuxTry(args);
+}
+
+/** The pane's root command + cwd, or null when the pane is gone. */
+function paneStartAndPath(paneId: string): Promise<{ start: string; path: string } | null> {
+  return tmuxRun(["display", "-p", "-t", paneId, "#{pane_start_command}\t#{pane_current_path}"])
+    .then((out) => {
+      const [start = "", path = ""] = out.split("\t");
+      return { start, path };
+    })
+    .catch(() => null);
+}
+
+/** Stop the agent in `paneId`: interrupt + authority cleanup. The pane (and
+ *  its shell, if any) stays open — `kill-pane` is deliberately NOT offered
+ *  over the socket; that is a human, confirmed-destructive verb. */
+export async function stopAgent(paneId: string): Promise<{ paneId: string; stopped: true }> {
+  const live = await paneStartAndPath(paneId);
+  if (!live) throw new ControlVerbError("not-found", `no pane "${paneId}"`);
+  await interruptAgent(paneId);
+  await clearAgentAuthority(paneId);
+  return { paneId, stopped: true };
+}
+
+/**
+ * Restart the agent in `paneId` running `command`, using the app's two
+ * strategies: a SHELL-hosted agent is interrupted and relaunched via
+ * send-keys (the shell survives to type into); an agent that IS the pane's
+ * own process is respawned in place (ctrl-c would end the pane).
+ */
+export async function restartAgent(
+  paneId: string,
+  command: string,
+): Promise<{ paneId: string; command: string; strategy: "relaunch" | "respawn" }> {
+  const live = await paneStartAndPath(paneId);
+  if (!live) throw new ControlVerbError("not-found", `no pane "${paneId}"`);
+  if (paneHostsShell(live.start, getManifests())) {
+    await interruptAgent(paneId);
+    await clearAgentAuthority(paneId);
+    await sleep(RESTART_GRACE_MS);
+    for (const args of relaunchArgs(paneId, command)) await tmuxTry(args);
+    return { paneId, command, strategy: "relaunch" };
+  }
+  await clearAgentAuthority(paneId);
+  await tmuxTry(respawnArgs(paneId, command, live.path || null));
+  return { paneId, command, strategy: "respawn" };
+}