tmux-ide 2.7.0 → 2.9.0-beta.5

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

@@ -0,0 +1,237 @@
+/**
+ * The control-socket server — `tmux-ide serve` (M23.3).
+ *
+ * NDJSON frames over a local Unix socket (default `~/.tmux-ide/control.sock`,
+ * mode 0600). Agent loops connect once and drive the fleet — request/response
+ * verbs plus PUSHED agent-status events after `subscribe` — instead of
+ * spawning a CLI process per call. Protocol schemas live in
+ * `@tmux-ide/contracts` (control.ts); verb handlers in `./verbs.ts` call the
+ * SAME data layer the CLI cases do.
+ *
+ * HOST DECISION (the tradeoff, considered before building):
+ *   (a) `tmux-ide serve` — an EXPLICIT foreground process. Costs the user a
+ *       deliberate start, dies with them, trivially restartable after a code
+ *       change, and its lifetime states its purpose.
+ *   (b) piggyback on the `_tmux-ide-chrome` updater tick — always running for
+ *       adopted fleets, but chrome-lifecycle-coupled: unadopting the last
+ *       session would kill the API mid-conversation, `adopt` would grow a
+ *       network-ish responsibility, and the updater's contract ("never let a
+ *       bad tick break the bars") is the wrong place for a protocol surface.
+ *   (c) socket-activated per-connection handlers — zero resident cost, but
+ *       every connection pays a full node boot (the latency the socket exists
+ *       to remove) and no resident process means no push events and no
+ *       persistent status tracker (the cross-tick `done` needs history).
+ *   CHOSEN: (a), deliberately WITHOUT auto-start. The old command-center HTTP
+ *   server is the cautionary tale: an implicitly-running daemon accretes
+ *   scope. This surface stays minimal — session-control verbs only, no feed,
+ *   no chat, no network listener — and the CLI only uses the socket
+ *   OPPORTUNISTICALLY (`--socket` fast-paths fall back to polling when no
+ *   server is up). An agent that wants the socket runs `tmux-ide serve`
+ *   itself; the process it spawned is the process it owns.
+ *
+ * SECURITY: local user only. The socket is chmod 0600, there is no network
+ * transport, no tokens (filesystem permissions ARE the auth). The #90 bridge
+ * that exposes this to a native app layers a WS server ON TOP later — each
+ * NDJSON frame maps 1:1 to a WS text message, so that bridge is mechanical
+ * and this file never grows remote scope.
+ *
+ * EVENTS: while at least one connection is subscribed, a detection tick
+ * (same cadence and diff as the chrome updater, one persistent tracker)
+ * computes the fleet and pushes session-level status transitions. No
+ * subscribers → no tick → an idle server does nothing. The tick does NOT
+ * write events.jsonl — the chrome updater owns the log; this stream is
+ * transport, not history.
+ */
+import { chmodSync, existsSync, mkdirSync, statSync, unlinkSync } from "node:fs";
+import { createServer, connect, type Server, type Socket } from "node:net";
+import { dirname } from "node:path";
+import { CONTROL_PROTOCOL_VERSION, type AgentStatusEvent } from "@tmux-ide/contracts";
+import { IdeError } from "../lib/errors.ts";
+import { resolveRuntimeNamespace } from "../lib/runtime-namespace.ts";
+import { createStatusTracker, type AgentStatus } from "../tui/detect/classify.ts";
+import { diffFleet } from "../tui/chrome/events.ts";
+import { fleetStatuses, TICK_MS } from "../tui/chrome/updater.ts";
+import { listTeamProjects } from "../tui/team/projects.ts";
+import { dispatchLine } from "./dispatch.ts";
+import { createFanout } from "./fanout.ts";
+import { createFrameSplitter, encodeFrame } from "./frames.ts";
+import { createVerbHandlers } from "./verbs.ts";
+
+/** The default socket path — under the state home so `TMUX_IDE_HOME` scopes
+ *  tests away from the real user socket. */
+export function defaultControlSocketPath(): string {
+  return resolveRuntimeNamespace().controlSocketPath;
+}
+
+export interface ControlServerOptions {
+  socketPath?: string;
+  /** Diagnostics sink (the CLI passes stderr). Default: silent. */
+  log?: (message: string) => void;
+  /** Event-tick cadence override (tests); defaults to the updater's TICK_MS. */
+  tickMs?: number;
+}
+
+export interface ControlServer {
+  socketPath: string;
+  close(): Promise<void>;
+}
+
+/**
+ * Claim `path`: refuse anything that exists and is not a socket (NEVER
+ * unlink a foreign file), refuse a socket another live server answers on,
+ * and unlink a stale socket left by a dead server.
+ */
+async function claimSocketPath(path: string): Promise<void> {
+  if (!existsSync(path)) return;
+  if (!statSync(path).isSocket()) {
+    throw new IdeError(
+      `${path} exists and is not a socket — refusing to remove it. ` +
+        `Pass a different --socket path.`,
+      { code: "USAGE", exitCode: 1 },
+    );
+  }
+  const alive = await new Promise<boolean>((resolve) => {
+    const probe: Socket = connect(path);
+    const done = (result: boolean) => {
+      probe.destroy();
+      resolve(result);
+    };
+    probe.once("connect", () => done(true));
+    probe.once("error", () => done(false));
+    probe.setTimeout(500, () => done(false));
+  });
+  if (alive) {
+    throw new IdeError(`another server is already listening on ${path}`, {
+      code: "USAGE",
+      exitCode: 1,
+    });
+  }
+  unlinkSync(path); // stale socket from a dead server — safe to rebind
+}
+
+/** Start the server. Resolves once the socket is listening (mode 0600). */
+export async function startControlServer(opts: ControlServerOptions = {}): Promise<ControlServer> {
+  const socketPath = opts.socketPath ?? defaultControlSocketPath();
+  const log = opts.log ?? (() => {});
+  const tickMs = opts.tickMs ?? TICK_MS;
+
+  mkdirSync(dirname(socketPath), { recursive: true });
+  await claimSocketPath(socketPath);
+
+  // ONE tracker for the server's lifetime, shared by the verbs and the event
+  // tick — cross-tick `done` (working→idle) is only observable with history.
+  const tracker = createStatusTracker();
+  const handlers = createVerbHandlers({ tracker });
+
+  // The event tick: runs ONLY while subscribers exist (fanout edges), diffs
+  // the fleet exactly like the chrome updater, pushes transitions.
+  const prevState = new Map<string, AgentStatus>();
+  let timer: ReturnType<typeof setInterval> | null = null;
+  const tick = (): void => {
+    try {
+      const { events, state } = diffFleet(prevState, fleetStatuses(listTeamProjects(tracker)));
+      prevState.clear();
+      for (const [name, status] of state) prevState.set(name, status);
+      const ts = new Date().toISOString();
+      for (const ev of events) fanout.emit({ ts, ...ev });
+    } catch (err) {
+      log(`event tick failed: ${(err as Error).message}`);
+    }
+  };
+  const fanout = createFanout<AgentStatusEvent>({
+    onFirst: () => {
+      tick(); // seed immediately — the first events carry the current fleet (from: null)
+      timer = setInterval(tick, tickMs);
+    },
+    onLast: () => {
+      if (timer) clearInterval(timer);
+      timer = null;
+      prevState.clear();
+    },
+  });
+
+  const connections = new Set<Socket>();
+  const server: Server = createServer((conn) => {
+    connections.add(conn);
+    conn.setEncoding("utf8");
+    const split = createFrameSplitter();
+    let unsubscribe: (() => void) | null = null;
+
+    const push = (ev: AgentStatusEvent): void => {
+      // One write per frame — JSON.stringify never contains a raw newline,
+      // so frames from concurrent requests can never interleave mid-message.
+      conn.write(encodeFrame({ v: CONTROL_PROTOCOL_VERSION, event: "agent-status", data: ev }));
+    };
+    const ctx = {
+      subscribe: () => {
+        unsubscribe ??= fanout.add(push);
+      },
+    };
+
+    conn.on("data", (chunk: string) => {
+      let lines: string[];
+      try {
+        lines = split(chunk);
+      } catch {
+        conn.destroy(); // frame overflow — a broken client, not a slow one
+        return;
+      }
+      for (const line of lines) {
+        // Handled CONCURRENTLY: a long `wait` must not block this
+        // connection's other requests (responses correlate by id).
+        void dispatchLine(line, handlers, ctx).then((response) => {
+          if (!conn.destroyed) conn.write(encodeFrame(response));
+        });
+      }
+    });
+    conn.on("close", () => {
+      unsubscribe?.();
+      connections.delete(conn);
+    });
+    conn.on("error", () => {
+      // close follows; nothing to do — never let a client error kill serve
+    });
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", (err: NodeJS.ErrnoException) => {
+      // Unix sockets cap the path at ~104 bytes (macOS sun_path) — surfaced
+      // as a bare EINVAL. Say what actually went wrong and how to fix it.
+      if ((err.code === "EINVAL" || err.code === "ENAMETOOLONG") && socketPath.length > 100) {
+        reject(
+          new IdeError(
+            `socket path is too long for a Unix socket (${socketPath.length} chars; the OS caps it around 104): ${socketPath}\n` +
+              `Pass a shorter path: tmux-ide serve --socket /tmp/tmux-ide-control.sock`,
+            { code: "USAGE", exitCode: 1 },
+          ),
+        );
+        return;
+      }
+      reject(err);
+    });
+    server.listen(socketPath, () => {
+      server.removeAllListeners("error");
+      resolve();
+    });
+  });
+  chmodSync(socketPath, 0o600);
+  log(`listening on ${socketPath}`);
+
+  return {
+    socketPath,
+    close: () =>
+      new Promise<void>((resolve) => {
+        if (timer) clearInterval(timer);
+        timer = null;
+        for (const conn of connections) conn.destroy(); // clients see EOF
+        server.close(() => {
+          try {
+            unlinkSync(socketPath);
+          } catch {
+            // already gone
+          }
+          resolve();
+        });
+      }),
+  };
+}

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

@@ -0,0 +1,118 @@
+/**
+ * The v1 verb handlers — each one a THIN adapter from validated params to
+ * the SAME data-layer functions the CLI cases call (report/sessions/wait/
+ * send/agent-explain/lifecycle). No fleet logic lives here; if a verb needs
+ * logic a CLI case has inline, the logic moves to the data layer and both
+ * point at it (that's how `wait` and `send` got their shared cores).
+ */
+import {
+  agentsParamsSchema,
+  explainParamsSchema,
+  restartAgentParamsSchema,
+  sendParamsSchema,
+  spawnParamsSchema,
+  stopAgentParamsSchema,
+  waitParamsSchema,
+} from "@tmux-ide/contracts";
+import type { ZodType } from "zod";
+import { buildReport } from "../agent-explain.ts";
+import { deliverMessage } from "../send.ts";
+import type { StatusTracker } from "../tui/detect/classify.ts";
+import { toFleetJson } from "../tui/team/report.ts";
+import { listTeamProjects } from "../tui/team/projects.ts";
+import { listTeamSessions } from "../tui/team/sessions.ts";
+import { waitForAgentStatus, waitForOutputMatch } from "../tui/team/wait.ts";
+import { ControlVerbError, type VerbHandler } from "./dispatch.ts";
+import { resolveLaunchCommand, restartAgent, spawnAgent, stopAgent } from "./lifecycle.ts";
+
+/** Validate `params` against a verb's schema, or answer `bad-request`. */
+function parse<T>(schema: ZodType<T>, params: unknown): T {
+  const result = schema.safeParse(params);
+  if (!result.success) {
+    const issue = result.error.issues[0];
+    const at = issue?.path?.length ? ` at ${issue.path.join(".")}` : "";
+    throw new ControlVerbError("bad-request", `invalid params${at}: ${issue?.message ?? "?"}`);
+  }
+  return result.data;
+}
+
+/**
+ * Build the handler map. `tracker` is the server's ONE persistent status
+ * tracker (shared with the event tick) so `fleet`/`agents` see the
+ * cross-tick `done` transition exactly like the chrome updater does —
+ * a fresh tracker per call could never observe working→idle.
+ */
+export function createVerbHandlers(ctx: { tracker: StatusTracker }): Record<string, VerbHandler> {
+  return {
+    fleet: () => toFleetJson(listTeamProjects(ctx.tracker)),
+
+    agents: (params) => {
+      const p = parse(agentsParamsSchema, params);
+      const sessions = listTeamSessions(ctx.tracker);
+      const scoped = p.session ? sessions.filter((s) => s.name === p.session) : sessions;
+      if (p.session && scoped.length === 0) {
+        throw new ControlVerbError("not-found", `no session "${p.session}"`);
+      }
+      return { agents: scoped.flatMap((s) => s.agents ?? []) };
+    },
+
+    send: (params) => {
+      const p = parse(sendParamsSchema, params);
+      return deliverMessage(p);
+    },
+
+    wait: async (params) => {
+      const p = parse(waitParamsSchema, params);
+      if (p.kind === "output") {
+        try {
+          new RegExp(p.match);
+        } catch (err) {
+          throw new ControlVerbError(
+            "bad-request",
+            `invalid match regex: ${(err as Error).message}`,
+          );
+        }
+      }
+      const result =
+        p.kind === "agent-status"
+          ? await waitForAgentStatus(p.session, p.status, { timeoutMs: p.timeoutMs })
+          : await waitForOutputMatch(p.target, p.match, { timeoutMs: p.timeoutMs });
+      if (!result.ok) {
+        const what =
+          p.kind === "agent-status"
+            ? `"${p.session}" to reach status "${p.status}"`
+            : `${p.target} output to match /${p.match}/`;
+        throw new ControlVerbError(
+          "timeout",
+          `timed out after ${result.timedOutAfterMs}ms waiting for ${what}`,
+        );
+      }
+      return result;
+    },
+
+    spawn: (params) => {
+      const p = parse(spawnParamsSchema, params);
+      return spawnAgent({ ...p, command: resolveLaunchCommand(p) });
+    },
+
+    "restart-agent": (params) => {
+      const p = parse(restartAgentParamsSchema, params);
+      return restartAgent(p.paneId, resolveLaunchCommand(p));
+    },
+
+    "stop-agent": (params) => {
+      const p = parse(stopAgentParamsSchema, params);
+      return stopAgent(p.paneId);
+    },
+
+    explain: (params) => {
+      const p = parse(explainParamsSchema, params);
+      return buildReport(p.target);
+    },
+
+    subscribe: (_params, verbCtx) => {
+      verbCtx.subscribe();
+      return { subscribed: true, events: ["agent-status"] };
+    },
+  };
+}

package/packages/daemon/src/detect.ts

@@ -2,6 +2,7 @@ import { resolve, basename } from "node:path";
 import { readFileSync, existsSync } from "node:fs";
 import { writeConfig } from "./lib/yaml-io.ts";
 import type { IdeConfig } from "./types.ts";
+import { resolveProjectConfigContext } from "./lib/config-context.ts";
 
 interface DetectedStack {
   packageManager: string | null;
@@ -142,8 +143,8 @@ export function suggestConfig(dir: string, detected: DetectedStack): IdeConfig {
       {
         size: "70%",
         panes: [
-          { title: "Claude 1", command: "claude" },
-          { title: "Claude 2", command: "claude" },
+          { id: "agent-1", title: "Claude 1", command: "claude" },
+          { id: "agent-2", title: "Claude 2", command: "claude" },
         ],
       },
       {
@@ -157,42 +158,42 @@ export function suggestConfig(dir: string, detected: DetectedStack): IdeConfig {
 
   // Add 3rd claude pane for complex stacks
   if (frameworks.length >= 2) {
-    config.rows[0]!.panes.push({ title: "Claude 3", command: "claude" });
+    config.rows[0]!.panes.push({ id: "agent-3", title: "Claude 3", command: "claude" });
   }
 
   // Add dev servers
   if (frameworks.includes("next")) {
-    bottom.push({ title: "Next.js", command: `${run} dev` });
+    bottom.push({ id: "dev", title: "Next.js", command: `${run} dev` });
   } else if (frameworks.includes("vite")) {
-    bottom.push({ title: "Vite", command: `${run} dev` });
+    bottom.push({ id: "dev", title: "Vite", command: `${run} dev` });
   } else if (frameworks.includes("nuxt")) {
-    bottom.push({ title: "Nuxt", command: `${run} dev` });
+    bottom.push({ id: "dev", title: "Nuxt", command: `${run} dev` });
   } else if (frameworks.includes("remix")) {
-    bottom.push({ title: "Remix", command: `${run} dev` });
+    bottom.push({ id: "dev", title: "Remix", command: `${run} dev` });
   } else if (frameworks.includes("astro")) {
-    bottom.push({ title: "Astro", command: `${run} dev` });
+    bottom.push({ id: "dev", title: "Astro", command: `${run} dev` });
   } else if (frameworks.includes("svelte")) {
-    bottom.push({ title: "SvelteKit", command: `${run} dev` });
+    bottom.push({ id: "dev", title: "SvelteKit", command: `${run} dev` });
   } else if (frameworks.includes("fastapi")) {
-    bottom.push({ title: "FastAPI", command: "uvicorn main:app --reload" });
+    bottom.push({ id: "dev", title: "FastAPI", command: "uvicorn main:app --reload" });
   } else if (frameworks.includes("django")) {
-    bottom.push({ title: "Django", command: "python manage.py runserver" });
+    bottom.push({ id: "dev", title: "Django", command: "python manage.py runserver" });
   } else if (frameworks.includes("flask")) {
-    bottom.push({ title: "Flask", command: "flask run --reload" });
+    bottom.push({ id: "dev", title: "Flask", command: "flask run --reload" });
   } else if (frameworks.includes("cargo")) {
-    bottom.push({ title: "Cargo", command: "cargo watch -x run" });
+    bottom.push({ id: "dev", title: "Cargo", command: "cargo watch -x run" });
   } else if (frameworks.includes("go")) {
-    bottom.push({ title: "Go", command: "go run ." });
+    bottom.push({ id: "dev", title: "Go", command: "go run ." });
   } else if (detected.devCommand) {
-    bottom.push({ title: "Dev Server", command: detected.devCommand });
+    bottom.push({ id: "dev", title: "Dev Server", command: detected.devCommand });
   }
 
   if (frameworks.includes("convex")) {
-    bottom.push({ title: "Convex", command: "npx convex dev" });
+    bottom.push({ id: "convex", title: "Convex", command: "npx convex dev" });
   }
 
   // Always add shell
-  bottom.push({ title: "Shell" });
+  bottom.push({ id: "shell", title: "Shell" });
 
   return config;
 }
@@ -201,7 +202,9 @@ export async function detect(
   targetDir: string | undefined,
   { json, write }: { json?: boolean; write?: boolean } = {},
 ): Promise<void> {
-  const dir = resolve(targetDir ?? ".");
+  const inputDir = resolve(targetDir ?? ".");
+  const context = write ? await resolveProjectConfigContext(inputDir) : null;
+  const dir = context?.configWriteRoot ?? inputDir;
   const detected = detectStack(dir);
   const suggested = suggestConfig(dir, detected);
 
@@ -214,7 +217,7 @@ export async function detect(
         detected.frameworks.length > 0
           ? detected.frameworks.join(" + ")
           : (detected.language ?? "generic project");
-      console.log(`Detected ${desc}. Created ide.yml.`);
+      console.log(`Detected ${desc}. Created .tmux-ide/workspace.yml.`);
       console.log("\nWhy this layout:");
       for (const reason of detected.reasons) {
         console.log(`  - ${reason}`);
@@ -237,7 +240,9 @@ export async function detect(
   for (const reason of detected.reasons) {
     console.log(`  - ${reason}`);
   }
-  console.log("\nRun with --write to create ide.yml, or --json to see the suggested config.");
+  console.log(
+    "\nRun with --write to create .tmux-ide/workspace.yml, or --json to see the suggested config.",
+  );
 }
 
 function pushFramework(detected: DetectedStack, framework: string, reason: string): void {