tmux-ide 2.1.5 → 2.6.1

package/packages/contracts/src/ide-config.ts

@@ -0,0 +1,170 @@
+import { z } from "zod";
+import { AuthConfigSchema } from "./lib-internal/auth.ts";
+import { HQConfigSchema } from "./lib-internal/hq.ts";
+
+const sizeField = z
+  .string()
+  .regex(/^[1-9]\d*%$/)
+  .refine((v) => parseInt(v) <= 100);
+
+export const ThemeConfigSchema = z.object({
+  accent: z.string().optional(),
+  border: z.string().optional(),
+  bg: z.string().optional(),
+  fg: z.string().optional(),
+});
+
+export const PaneSchema = z.object({
+  title: z.string().optional(),
+  command: z.string().optional(),
+  type: z
+    .enum([
+      "explorer",
+      "changes",
+      "preview",
+      "tasks",
+      "costs",
+      "config",
+      "mission-control",
+      "sidebar",
+    ])
+    .optional(),
+  target: z.string().optional(),
+  dir: z.string().optional(),
+  size: sizeField.optional(),
+  focus: z.boolean().optional(),
+  env: z.record(z.string(), z.union([z.string(), z.number()])).optional(),
+  role: z.enum(["lead", "teammate", "planner", "validator", "researcher"]).optional(),
+  task: z.string().optional(),
+  specialty: z.string().optional(),
+  skill: z.string().optional(),
+});
+
+export const RowSchema = z.object({
+  size: sizeField.optional(),
+  panes: z.array(PaneSchema).min(1),
+});
+
+export const WebhookConfigSchema = z.object({
+  url: z.string(),
+  events: z.array(z.string()).optional(),
+  secret: z.string().optional(),
+});
+
+export const OrchestratorYamlConfigSchema = z.object({
+  enabled: z.boolean().optional(),
+  port: z.number().int().positive().optional(),
+  auto_dispatch: z.boolean().optional(),
+  stall_timeout: z.number().optional(),
+  poll_interval: z.number().min(100).optional(),
+  master_pane: z.string().optional(),
+  before_run: z.string().optional(),
+  after_run: z.string().optional(),
+  dispatch_mode: z.enum(["tasks", "goals", "missions"]).optional(),
+  max_concurrent_agents: z.number().min(1).max(50).optional(),
+  widgets: z.boolean().optional(),
+  webhooks: z.array(WebhookConfigSchema).optional(),
+  services: z
+    .record(
+      z.string(),
+      z.object({
+        command: z.string(),
+        port: z.number().optional(),
+        healthcheck: z.string().optional(),
+      }),
+    )
+    .optional(),
+  research: z
+    .object({
+      enabled: z.boolean().optional(),
+      triggers: z
+        .object({
+          mission_start: z.boolean().optional(),
+          milestone_progress: z.number().min(0).optional(),
+          milestone_complete: z.boolean().optional(),
+          periodic_minutes: z.number().min(0).optional(),
+          retry_cluster: z.boolean().optional(),
+          stall_detected: z.boolean().optional(),
+          discovered_issue: z.boolean().optional(),
+        })
+        .optional(),
+    })
+    .optional(),
+});
+
+export const TunnelConfigSchema = z.object({
+  provider: z.enum(["tailscale", "ngrok", "cloudflare"]),
+  auto_start: z.boolean().optional(),
+  port: z.number().int().positive().optional(),
+  domain: z.string().optional(),
+  authtoken: z.string().optional(),
+});
+
+export const CommandCenterConfigSchema = z.object({
+  port: z.number().optional(),
+  enabled: z.boolean().optional(),
+});
+
+export const DashboardConfigSchema = z.object({
+  port: z.number().int().positive().optional(),
+});
+
+/**
+ * The app nav-column sidebar sugar. `sidebar: true` injects a full-height left
+ * column (default width) at launch; `sidebar: { width: "30" }` sets its column
+ * width (in tmux cols, as a string to match the CLI/tmux world). `false` /
+ * omitted means no sidebar.
+ */
+export const SidebarConfigSchema = z.union([
+  z.boolean(),
+  z.object({ width: z.string().optional() }),
+]);
+
+export const IdeConfigSchema = z.object({
+  name: z.string().optional(),
+  before: z.string().optional(),
+  team: z
+    .object({
+      name: z.string(),
+      model: z.string().optional(),
+      permissions: z.array(z.string()).optional(),
+    })
+    .optional(),
+  rows: z.array(RowSchema).min(1),
+  sidebar: SidebarConfigSchema.optional(),
+  theme: ThemeConfigSchema.optional(),
+  orchestrator: OrchestratorYamlConfigSchema.optional(),
+  command_center: CommandCenterConfigSchema.optional(),
+  dashboard: DashboardConfigSchema.optional(),
+  auth: AuthConfigSchema.optional(),
+  tunnel: TunnelConfigSchema.optional(),
+  hq: HQConfigSchema.optional(),
+});
+
+export const PaneActionSchema = z.object({
+  targetPane: z.string(),
+  title: z.string().nullable(),
+  chdir: z.string().nullable(),
+  exports: z.array(z.string()),
+  command: z.string().nullable(),
+  widgetType: z.string().nullable(),
+  widgetTarget: z.string().nullable(),
+  paneRole: z.string().nullable(),
+  paneType: z.string().nullable(),
+});
+
+export const SessionStateSchema = z.object({
+  running: z.boolean(),
+  reason: z.string().nullable(),
+});
+
+export type ThemeConfig = z.infer<typeof ThemeConfigSchema>;
+export type Pane = z.infer<typeof PaneSchema>;
+export type Row = z.infer<typeof RowSchema>;
+export type OrchestratorYamlConfig = z.infer<typeof OrchestratorYamlConfigSchema>;
+export type SidebarConfig = z.infer<typeof SidebarConfigSchema>;
+export type CommandCenterConfig = z.infer<typeof CommandCenterConfigSchema>;
+export type DashboardConfig = z.infer<typeof DashboardConfigSchema>;
+export type IdeConfig = z.infer<typeof IdeConfigSchema>;
+export type PaneAction = z.infer<typeof PaneActionSchema>;
+export type SessionState = z.infer<typeof SessionStateSchema>;

package/packages/contracts/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @tmux-ide/contracts — shared Zod schemas for the daemon ↔ dashboard
+ * boundary. Dashboard, packages/daemon, and any future v2 surfaces all
+ * import from this single source of truth.
+ *
+ * Adding a schema? Put it in either `domain.ts` (runtime data: tasks,
+ * missions, sessions, …) or `ide-config.ts` (the on-disk ide.yml
+ * shape). Both files are re-exported wholesale below — no manual
+ * registration needed.
+ *
+ * The `lib-internal/` directory holds schema-only helpers (auth, hq)
+ * that ide-config depends on — they are exported transitively here
+ * so consumers don't have to deep-import.
+ */
+
+export * from "./lib-internal/auth.ts";
+export * from "./lib-internal/hq.ts";
+export * from "./ide-config.ts";
+export * from "./domain.ts";
+export * from "./tmux.ts";
+export * from "./workspace.ts";
+export * from "./actions-contract.ts";
+export * from "./actions-errors.ts";
+export * from "./terminals.ts";

package/packages/contracts/src/lib-internal/hq.ts

@@ -0,0 +1,38 @@
+// Based on VibeTunnel (MIT) — github.com/amantus-ai/vibetunnel
+//
+// Schemas + serializable interfaces only. The daemon-only `RemoteMachine`
+// runtime type (Date / Set fields) lives in @tmux-ide/daemon's lib/hq —
+// not here.
+import { z } from "zod";
+
+export interface HQConfig {
+  enabled: boolean;
+  role: "hq" | "remote";
+  hq_url?: string;
+  secret?: string;
+  heartbeat_interval?: number;
+  machine_name?: string;
+}
+
+export interface RegistrationPayload {
+  id: string;
+  name: string;
+  url: string;
+  token: string;
+}
+
+export const RegistrationPayloadSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  url: z.string().url(),
+  token: z.string().min(1),
+});
+
+export const HQConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  role: z.enum(["hq", "remote"]),
+  hq_url: z.string().url().optional(),
+  secret: z.string().optional(),
+  heartbeat_interval: z.number().min(1000).default(15000),
+  machine_name: z.string().optional(),
+});

package/packages/contracts/src/terminals.ts

@@ -0,0 +1,116 @@
+/**
+ * Multi-terminal registry contracts (G20-P1).
+ *
+ * A `Terminal` is a *named pool entry* — metadata about a PTY the
+ * daemon may or may not have spawned yet. The daemon's existing
+ * `/ws/pty/:id` endpoint owns the actual process lifecycle; this
+ * registry exists so the UI can persist tab labels + restore them
+ * across reloads, and so deterministic scope/script tabs collapse to
+ * the same id (re-opens land on the running scrollback).
+ */
+
+import { z } from "zod";
+
+// ---------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------
+
+export type TerminalKind = "shell" | "setup" | "run" | "teardown";
+
+export interface Terminal {
+  /** Deterministic id for scope/script tabs; UUID for ad-hoc tabs. */
+  id: string;
+  /** Session name the terminal belongs to. */
+  projectId: string;
+  /** Sub-grouping inside a session (mission id, dir hash, …). Free-form. */
+  scopeId: string;
+  /** Free-text display name. The tab strip renames this without changing id. */
+  name: string;
+  kind: TerminalKind;
+  createdAt: string;
+  updatedAt: string;
+  /** Set when the id was derived via `createScriptTerminalId` so the
+   *  client can show a "shared script" badge in the tab strip. */
+  scripted?: boolean;
+}
+
+/** Live runtime info — derived from the daemon's bridge registry, not
+ *  the JSON store. Combined with `Terminal` for the list endpoint. */
+export interface TerminalRuntime {
+  running: boolean;
+  cols?: number;
+  rows?: number;
+  /** Bytes available in the replay ring buffer when a client subscribes. */
+  replayBytes?: number;
+}
+
+export interface TerminalWithRuntime extends Terminal {
+  runtime: TerminalRuntime;
+}
+
+export interface TerminalListResponse {
+  terminals: TerminalWithRuntime[];
+}
+
+// ---------------------------------------------------------------------
+// Deterministic id
+// ---------------------------------------------------------------------
+
+/** Build a deterministic 32-char id from `(projectId, scopeId, kind,
+ *  script)`. Two different callers asking for "the run script terminal
+ *  for project X, scope Y, script Z" get the same id and land on the
+ *  same bridge — which means scrollback survives a browser reload. */
+export async function createScriptTerminalId(args: {
+  projectId: string;
+  scopeId?: string;
+  /** Backward-compat alias for `scopeId`. */
+  taskId?: string;
+  kind: TerminalKind;
+  script: string;
+}): Promise<string> {
+  const scope = args.scopeId ?? args.taskId;
+  if (!scope) {
+    throw new Error("createScriptTerminalId: scopeId (or taskId) is required");
+  }
+  const key = `${args.projectId}::${scope}::${args.kind}::${args.script}`;
+  const data = new TextEncoder().encode(key);
+  const digest = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(digest))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("")
+    .slice(0, 32);
+}
+
+// ---------------------------------------------------------------------
+// Zod request schemas
+// ---------------------------------------------------------------------
+
+export const terminalKindSchema = z.enum(["shell", "setup", "run", "teardown"]);
+
+export const terminalCreateRequestSchema = z
+  .object({
+    scopeId: z.string().trim().min(1).max(256),
+    name: z.string().trim().min(1).max(120),
+    kind: terminalKindSchema.optional(),
+    /** Provide for script tabs to opt into deterministic id collapse. */
+    script: z.string().max(2048).optional(),
+    /** Explicit id wins. Used by the dashboard to reserve a known id
+     *  (e.g. the default shell tab derived from session.dir). */
+    id: z
+      .string()
+      .trim()
+      .min(8)
+      .max(64)
+      .regex(/^[A-Za-z0-9_-]+$/u, "id may only contain alphanumerics, '-', '_'")
+      .optional(),
+  })
+  .refine((v) => v.kind !== undefined || v.script === undefined, {
+    message: "script requires kind",
+    path: ["script"],
+  });
+export type TerminalCreateRequest = z.infer<typeof terminalCreateRequestSchema>;
+
+export const terminalRenameRequestSchema = z.object({
+  name: z.string().trim().min(1).max(120),
+});
+export type TerminalRenameRequest = z.infer<typeof terminalRenameRequestSchema>;

package/packages/contracts/src/tmux.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+
+/**
+ * Tmux state schemas — the canonical typed surface for tmux sessions,
+ * windows, panes, and pane addressing.
+ *
+ * Used by:
+ *   - packages/tmux-bridge — implementation that shells out to tmux.
+ *   - packages/daemon (session-monitor, discovery, command-center) —
+ *     materializes these shapes into the live runtime state.
+ *   - dashboard — consumes them via the typed REST/SSE clients.
+ *
+ * Adding a new addressing mode (e.g. byRegex) is intentionally a one-line
+ * discriminant change here; bridge resolvers must update in lockstep.
+ */
+
+export const TmuxPaneSchemaZ = z.object({
+  /** Stable tmux pane id (e.g. `%23`). */
+  id: z.string(),
+  /** Pane index within its window (zero-based). */
+  paneIndex: z.number().int().nonnegative(),
+  /** Window index within the session (zero-based). */
+  windowIndex: z.number().int().nonnegative(),
+  title: z.string().nullable(),
+  command: z.string().nullable(),
+  active: z.boolean(),
+});
+export type TmuxPane = z.infer<typeof TmuxPaneSchemaZ>;
+
+export const TmuxWindowSchemaZ = z.object({
+  index: z.number().int().nonnegative(),
+  name: z.string(),
+  panes: z.array(TmuxPaneSchemaZ),
+});
+export type TmuxWindow = z.infer<typeof TmuxWindowSchemaZ>;
+
+export const TmuxSessionSchemaZ = z.object({
+  name: z.string(),
+  windows: z.array(TmuxWindowSchemaZ),
+  /** Session creation time (epoch milliseconds). */
+  created: z.number().int().nonnegative(),
+  attached: z.boolean(),
+  /** Project directory the session was launched from, when known. */
+  projectDir: z.string().nullable(),
+});
+export type TmuxSession = z.infer<typeof TmuxSessionSchemaZ>;
+
+/**
+ * Discriminated union for addressing a pane. The bridge's resolver
+ * implements byId/byIndex/byTitle directly; byRole is resolved at the
+ * daemon layer (it requires reading the ide.yml-driven role mapping)
+ * and translated into a concrete address before reaching the bridge.
+ */
+export const TmuxPaneTargetSchemaZ = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("byId"), id: z.string() }),
+  z.object({ kind: z.literal("byIndex"), index: z.number().int().nonnegative() }),
+  z.object({ kind: z.literal("byTitle"), title: z.string() }),
+  z.object({ kind: z.literal("byRole"), role: z.string() }),
+]);
+export type TmuxPaneTarget = z.infer<typeof TmuxPaneTargetSchemaZ>;

package/packages/contracts/src/workspace.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+
+/**
+ * A workspace is a project the daemon is actively serving — identified by
+ * its tmux session name and bound to a project directory.
+ *
+ * The workspace registry replaces the historical single-session
+ * TMUX_IDE_SESSION env coupling, letting the daemon serve N projects in
+ * one process. Goal 12 of the t3-style consolidation; see T065.
+ */
+export const WorkspaceSchemaZ = z.object({
+  /** Stable workspace name (typically equal to tmux session name). */
+  name: z.string().min(1),
+  /** Tmux session this workspace maps to. */
+  sessionName: z.string().min(1),
+  /** Absolute project directory. */
+  projectDir: z.string().min(1),
+  /** Absolute path to the ide.yml driving this workspace. */
+  ideConfigPath: z.string().nullable(),
+  /** ISO timestamp of when the workspace was added. */
+  addedAt: z.string(),
+});
+export type Workspace = z.infer<typeof WorkspaceSchemaZ>;
+
+// ---------------------------------------------------------------------------
+// HTTP request / response shapes for /api/workspaces
+// ---------------------------------------------------------------------------
+
+export const WorkspaceListResponseSchemaZ = z.object({
+  workspaces: z.array(WorkspaceSchemaZ),
+});
+export type WorkspaceListResponse = z.infer<typeof WorkspaceListResponseSchemaZ>;
+
+export const AddWorkspaceRequestSchemaZ = z.object({
+  /** Absolute path to the project directory. */
+  projectDir: z.string().min(1),
+  /** Optional explicit workspace name. Auto-derived from basename when absent. */
+  name: z.string().min(1).optional(),
+  /** Optional override for the tmux session name (defaults to `name`). */
+  sessionName: z.string().min(1).optional(),
+  /** Optional ide.yml path the workspace was launched with. */
+  ideConfigPath: z.string().min(1).optional(),
+});
+export type AddWorkspaceRequest = z.infer<typeof AddWorkspaceRequestSchemaZ>;
+
+export const AddWorkspaceResponseSchemaZ = z.object({
+  workspace: WorkspaceSchemaZ,
+});
+export type AddWorkspaceResponse = z.infer<typeof AddWorkspaceResponseSchemaZ>;
+
+// ---------------------------------------------------------------------------
+// WebSocket event frames — fired on registry add/remove (including the
+// auto-reconcile loop that drops dead sessions). Kept here so dashboard /
+// daemon consumers share the exact discriminator strings.
+// ---------------------------------------------------------------------------
+
+export const WorkspaceAddedFrameSchemaZ = z.object({
+  type: z.literal("workspace.added"),
+  workspace: WorkspaceSchemaZ,
+});
+export type WorkspaceAddedFrame = z.infer<typeof WorkspaceAddedFrameSchemaZ>;
+
+export const WorkspaceRemovedFrameSchemaZ = z.object({
+  type: z.literal("workspace.removed"),
+  name: z.string(),
+});
+export type WorkspaceRemovedFrame = z.infer<typeof WorkspaceRemovedFrameSchemaZ>;

package/packages/daemon/dist/__tests__/support.d.ts

@@ -0,0 +1,7 @@
+import type { PaneInfo } from "../widgets/lib/pane-comms.ts";
+export declare function makePane(overrides?: Partial<PaneInfo>): PaneInfo;
+export declare class TestProject {
+    readonly dir: string;
+    constructor();
+    cleanup(): void;
+}

package/packages/daemon/dist/__tests__/support.js

@@ -0,0 +1,33 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+// ---------------------------------------------------------------------------
+// Factory: PaneInfo
+// ---------------------------------------------------------------------------
+export function makePane(overrides = {}) {
+    return {
+        id: "%1",
+        index: 0,
+        title: "Agent 1",
+        currentCommand: "zsh",
+        width: 80,
+        height: 24,
+        active: false,
+        role: null,
+        name: null,
+        type: null,
+        ...overrides,
+    };
+}
+// ---------------------------------------------------------------------------
+// TestProject: scratch temp directory
+// ---------------------------------------------------------------------------
+export class TestProject {
+    dir;
+    constructor() {
+        this.dir = mkdtempSync(join(tmpdir(), "tmux-ide-test-"));
+    }
+    cleanup() {
+        rmSync(this.dir, { recursive: true, force: true });
+    }
+}

package/packages/daemon/dist/agent-explain.d.ts

@@ -0,0 +1,45 @@
+import { type DetectedState } from "./tui/detect/manifest.ts";
+import { type AgentStatus, type InstantState } from "./tui/detect/classify.ts";
+export interface ExplainReport {
+    pane: {
+        id: string;
+        cmd: string;
+        pid: number;
+        title: string;
+    };
+    authority: {
+        raw: string | null;
+        state: string | null;
+        epoch: number | null;
+        ageSeconds: number | null;
+        stale: boolean;
+        verdict: AgentStatus | null;
+    };
+    hint: {
+        raw: string | null;
+        applied: boolean;
+    };
+    resolution: {
+        manifestId: string | null;
+        matchedCommand: string;
+        source: "hint" | "fast" | "tree" | "none";
+    };
+    states: Array<{
+        state: DetectedState;
+        matched: boolean;
+    }>;
+    winner: DetectedState | null;
+    instant: InstantState;
+    classification: AgentStatus;
+    bottomLines: string[];
+}
+/** Build the full report for a pane. Does all the io (tmux + ps + capture). */
+export declare function buildReport(target: string): ExplainReport;
+/** Render the report as colored human-readable text. */
+export declare function renderReport(r: ExplainReport, opts?: {
+    color?: boolean;
+}): string;
+/** CLI entry: build + print the report (human or JSON). */
+export declare function agentExplain(target: string, opts?: {
+    json?: boolean;
+}): void;