pi-tmux-session-map 0.3.0

package/src/domain/pane-info.ts

@@ -0,0 +1,92 @@
+import { normalizePaneKey } from "./pane-key.ts";
+import type { PaneInfo } from "./status.ts";
+
+export function parseTmuxIndex(value: string): number {
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+export function parsePaneInfoOutput(stdout: string, paneId: string): PaneInfo | undefined {
+  const trimmed = stdout.trim();
+  if (trimmed === "") {
+    return undefined;
+  }
+
+  const [rawPaneKey, sessionName, rawWindowIndex, rawPaneIndex] = trimmed.split("\t");
+  const paneKey = normalizePaneKey(rawPaneKey ?? "");
+  if (!paneKey || !sessionName) {
+    return undefined;
+  }
+
+  return {
+    backend: "tmux",
+    paneKey,
+    paneId,
+    sessionName,
+    windowIndex: parseTmuxIndex(rawWindowIndex ?? "0"),
+    paneIndex: parseTmuxIndex(rawPaneIndex ?? "0"),
+  };
+}
+
+type ZellijPane = {
+  id?: unknown;
+  is_plugin?: unknown;
+  tab_position?: unknown;
+};
+
+function isZellijPane(value: unknown): value is ZellijPane {
+  return typeof value === "object" && value !== null;
+}
+
+export function mexPaneInfo(sessionId: string | undefined): PaneInfo | undefined {
+  if (!sessionId) {
+    return undefined;
+  }
+  return {
+    backend: "mex",
+    paneKey: `mex:${sessionId}`,
+    paneId: sessionId,
+    sessionName: sessionId,
+    windowIndex: 0,
+    paneIndex: 0,
+  };
+}
+
+export function parseZellijPaneInfo(
+  stdout: string,
+  sessionName: string,
+  paneId: string,
+): PaneInfo | undefined {
+  if (!sessionName || !paneId) {
+    return undefined;
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(stdout);
+  } catch {
+    return undefined;
+  }
+  if (!Array.isArray(raw)) {
+    return undefined;
+  }
+  const numericId = Number.parseInt(paneId, 10);
+  if (!Number.isFinite(numericId)) {
+    return undefined;
+  }
+  const pane = raw.find(
+    (entry) => isZellijPane(entry) && entry.is_plugin !== true && entry.id === numericId,
+  );
+  if (!isZellijPane(pane)) {
+    return undefined;
+  }
+  const tabPosition = typeof pane.tab_position === "number" ? pane.tab_position : 0;
+  const normalizedPaneId = `terminal_${numericId}`;
+  return {
+    backend: "zellij",
+    paneKey: `${sessionName}:${tabPosition}.${numericId}`,
+    paneId: normalizedPaneId,
+    sessionName,
+    windowIndex: tabPosition,
+    paneIndex: numericId,
+  };
+}

package/src/domain/pane-key.ts

@@ -0,0 +1,60 @@
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** tmux format string that yields a pane key stable across tmux server restarts. */
+export const PANE_KEY_FORMAT = "#{session_name}:#{window_index}.#{pane_index}";
+
+/**
+ * Default state directory for pane -> session-file mappings.
+ *
+ * One plain-text file per pane; the first line is the absolute path of the
+ * Pi session file that ran in that pane.
+ */
+export function defaultStateDir(): string {
+  return join(homedir(), ".local", "state", "pi", "tmux-sessions");
+}
+
+/**
+ * Sanitize a pane key for use as a file name.
+ *
+ * Keep in sync with consumers that resolve the mapping from shell, e.g. a
+ * `pi-tmux-resume` wrapper using `tr -c 'A-Za-z0-9._-' '_'`.
+ */
+export function sanitizeKey(key: string): string {
+  let result = "";
+  for (const byte of Buffer.from(key, "utf8")) {
+    const isDigit = byte >= 0x30 && byte <= 0x39;
+    const isUpper = byte >= 0x41 && byte <= 0x5a;
+    const isLower = byte >= 0x61 && byte <= 0x7a;
+    const isPunctuation = byte === 0x2e || byte === 0x5f || byte === 0x2d;
+    result += isDigit || isUpper || isLower || isPunctuation ? String.fromCharCode(byte) : "_";
+  }
+  return result;
+}
+
+export function hashKey(key: string): string {
+  return createHash("sha256").update(key).digest("hex").slice(0, 12);
+}
+
+export function keyFileStem(key: string): string {
+  const sanitized = sanitizeKey(key).slice(0, 120).replace(/^\.+$/, "_");
+  const prefix = sanitized === "" ? "pane" : sanitized;
+  return `${prefix}-${hashKey(key)}`;
+}
+
+/** File name of the mapping file for a raw pane key. */
+export function mappingFileName(key: string): string {
+  return `${keyFileStem(key)}.session`;
+}
+
+/** File name of the tws status file for a raw pane key. */
+export function statusFileName(key: string): string {
+  return `${keyFileStem(key)}.json`;
+}
+
+/** Normalize raw `tmux display-message` output into a pane key, if usable. */
+export function normalizePaneKey(stdout: string): string | undefined {
+  const key = stdout.trim();
+  return key === "" ? undefined : key;
+}

package/src/domain/restore-ack.ts

@@ -0,0 +1,77 @@
+import { join } from "node:path";
+
+import type { PaneInfo, SessionInfo } from "./status.ts";
+
+export type RestoreExpectation = {
+  token: string;
+  paneKey: string;
+  sessionId: string;
+  sessionFile: string;
+  ackDir: string;
+};
+
+export type RestoreAck = {
+  schema: 1;
+  status: "resumed" | "mismatch";
+  token: string;
+  expectedPaneKey: string;
+  actualPaneKey: string;
+  expectedSessionId: string;
+  actualSessionId: string;
+  expectedSessionFile: string;
+  actualSessionFile: string | null;
+  cwd: string;
+  sessionName: string | null;
+  reason: string;
+  acknowledgedAtMs: number;
+};
+
+export function restoreExpectationFromEnvironment(
+  env: NodeJS.ProcessEnv = process.env,
+): RestoreExpectation | undefined {
+  const token = env.PI_TMUX_RESTORE_TOKEN;
+  const paneKey = env.PI_TMUX_EXPECTED_PANE;
+  const sessionId = env.PI_TMUX_EXPECTED_SESSION_ID;
+  const sessionFile = env.PI_TMUX_EXPECTED_SESSION_FILE;
+  const ackDir = env.PI_TMUX_RESTORE_ACK_DIR;
+  if (!token || !paneKey || !sessionId || !sessionFile || !ackDir) {
+    return undefined;
+  }
+  return { token, paneKey, sessionId, sessionFile, ackDir };
+}
+
+export function buildRestoreAck(
+  expectation: RestoreExpectation,
+  pane: PaneInfo,
+  session: SessionInfo,
+  sessionId: string,
+  reason: string,
+  acknowledgedAtMs: number,
+): RestoreAck {
+  const matches = pane.paneKey === expectation.paneKey
+    && sessionId === expectation.sessionId
+    && session.sessionFile === expectation.sessionFile;
+  return {
+    schema: 1,
+    status: matches ? "resumed" : "mismatch",
+    token: expectation.token,
+    expectedPaneKey: expectation.paneKey,
+    actualPaneKey: pane.paneKey,
+    expectedSessionId: expectation.sessionId,
+    actualSessionId: sessionId,
+    expectedSessionFile: expectation.sessionFile,
+    actualSessionFile: session.sessionFile,
+    cwd: session.cwd,
+    sessionName: session.sessionName,
+    reason,
+    acknowledgedAtMs,
+  };
+}
+
+export function restoreAckPath(expectation: RestoreExpectation): string {
+  return join(expectation.ackDir, `${expectation.token}.json`);
+}
+
+export function serializeRestoreAck(ack: RestoreAck): string {
+  return `${JSON.stringify(ack)}\n`;
+}

package/src/domain/session-mapping.ts

@@ -0,0 +1,89 @@
+export type SessionMapping = {
+  schema: 2;
+  paneKey: string;
+  sessionFile: string;
+  sessionId: string;
+  cwd: string;
+  sessionName: string | null;
+  updatedAtMs: number;
+};
+
+export type ParsedSessionMapping =
+  | { format: "structured"; mapping: SessionMapping }
+  | { format: "legacy"; sessionFile: string };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function buildSessionMapping(
+  paneKey: string,
+  sessionFile: string,
+  sessionId: string,
+  cwd: string,
+  sessionName: string | null,
+  updatedAtMs: number,
+): SessionMapping {
+  return {
+    schema: 2,
+    paneKey,
+    sessionFile,
+    sessionId,
+    cwd,
+    sessionName,
+    updatedAtMs,
+  };
+}
+
+export function serializeSessionMapping(mapping: SessionMapping): string {
+  return `${JSON.stringify(mapping)}\n`;
+}
+
+export function parseSessionMapping(content: string): ParsedSessionMapping | undefined {
+  const trimmed = content.trim();
+  if (trimmed === "") {
+    return undefined;
+  }
+  if (!trimmed.startsWith("{")) {
+    return { format: "legacy", sessionFile: trimmed.split(/\r?\n/, 1)[0] ?? "" };
+  }
+
+  let value: unknown;
+  try {
+    value = JSON.parse(trimmed);
+  } catch {
+    return undefined;
+  }
+  if (
+    !isRecord(value)
+    || value.schema !== 2
+    || typeof value.paneKey !== "string"
+    || typeof value.sessionFile !== "string"
+    || typeof value.sessionId !== "string"
+    || typeof value.cwd !== "string"
+    || !(typeof value.sessionName === "string" || value.sessionName === null)
+    || typeof value.updatedAtMs !== "number"
+  ) {
+    return undefined;
+  }
+  return {
+    format: "structured",
+    mapping: {
+      schema: 2,
+      paneKey: value.paneKey,
+      sessionFile: value.sessionFile,
+      sessionId: value.sessionId,
+      cwd: value.cwd,
+      sessionName: value.sessionName,
+      updatedAtMs: value.updatedAtMs,
+    },
+  };
+}
+
+export function mappedSessionFile(content: string): string | undefined {
+  const parsed = parseSessionMapping(content);
+  if (!parsed) {
+    return undefined;
+  }
+  return parsed.format === "structured" ? parsed.mapping.sessionFile : parsed.sessionFile;
+}

package/src/domain/state.ts

@@ -0,0 +1,118 @@
+export type WorkState =
+  | "idle"
+  | "working"
+  | "retrying"
+  | "done"
+  | "cancelled"
+  | "incomplete"
+  | "failed"
+  | "shutdown";
+
+export type FinalWorkState = "done" | "cancelled" | "incomplete" | "failed";
+
+function isFinalWorkState(state: WorkState | null): state is FinalWorkState {
+  return state === "done" || state === "cancelled" || state === "incomplete" || state === "failed";
+}
+
+export type RuntimeState = {
+  startedAtMs: number | null;
+  finishedAtMs: number | null;
+  lastState: WorkState | null;
+  sequence: number;
+};
+
+export type StatusTransition = RuntimeState & {
+  state: WorkState;
+  shouldWrite: boolean;
+};
+
+export function createRuntimeState(): RuntimeState {
+  return {
+    startedAtMs: null,
+    finishedAtMs: null,
+    lastState: null,
+    sequence: 0,
+  };
+}
+
+export function nextStatusTransition(
+  current: RuntimeState,
+  state: WorkState,
+  nowMs: number,
+): StatusTransition {
+  const sequence = current.sequence + 1;
+
+  if (state === "shutdown" && isFinalWorkState(current.lastState)) {
+    return {
+      ...current,
+      sequence,
+      state,
+      shouldWrite: false,
+    };
+  }
+
+  if (state === "working") {
+    return {
+      startedAtMs: nowMs,
+      finishedAtMs: null,
+      lastState: "working",
+      sequence,
+      state,
+      shouldWrite: true,
+    };
+  }
+
+  if (state === "retrying") {
+    return {
+      startedAtMs: current.startedAtMs ?? nowMs,
+      finishedAtMs: null,
+      lastState: "retrying",
+      sequence,
+      state,
+      shouldWrite: true,
+    };
+  }
+
+  if (isFinalWorkState(state)) {
+    return {
+      startedAtMs: current.startedAtMs,
+      finishedAtMs: current.finishedAtMs ?? nowMs,
+      lastState: state,
+      sequence,
+      state,
+      shouldWrite: true,
+    };
+  }
+
+  return {
+    startedAtMs: state === "idle" ? null : current.startedAtMs,
+    finishedAtMs: state === "idle" ? null : current.finishedAtMs,
+    lastState: state,
+    sequence,
+    state,
+    shouldWrite: true,
+  };
+}
+
+export function refreshStatusTransition(current: RuntimeState, nowMs: number): StatusTransition {
+  const state = current.lastState ?? "idle";
+
+  if (state === "idle" && current.lastState === null) {
+    return nextStatusTransition(current, "idle", nowMs);
+  }
+
+  if (state === "working" && current.startedAtMs === null) {
+    return nextStatusTransition(current, "working", nowMs);
+  }
+
+  if (isFinalWorkState(state) && current.finishedAtMs === null) {
+    return nextStatusTransition(current, state, nowMs);
+  }
+
+  return {
+    ...current,
+    sequence: current.sequence + 1,
+    state,
+    shouldWrite: true,
+  };
+}

package/src/domain/status.ts

@@ -0,0 +1,65 @@
+import type { WorkState } from "./state.ts";
+
+export type PaneInfo = {
+  backend: "tmux" | "zellij" | "mex";
+  paneKey: string;
+  paneId: string;
+  sessionName: string;
+  windowIndex: number;
+  paneIndex: number;
+};
+
+export type SessionInfo = {
+  cwd: string;
+  sessionFile: string | null;
+  sessionName: string | null;
+};
+
+export type TwsStatusPayload = {
+  schema: 1;
+  agent: "pi";
+  backend: "tmux" | "zellij" | "mex";
+  pane_id: string;
+  pane_key: string;
+  tmux_session_name: string;
+  window_index: number;
+  pane_index: number;
+  cwd: string;
+  session_file: string | null;
+  session_name: string | null;
+  state: WorkState;
+  updated_at_ms: number;
+  started_at_ms: number | null;
+  finished_at_ms: number | null;
+};
+
+export function buildTwsStatusPayload(
+  pane: PaneInfo,
+  session: SessionInfo,
+  state: WorkState,
+  updatedAtMs: number,
+  startedAtMs: number | null,
+  finishedAtMs: number | null,
+): TwsStatusPayload {
+  return {
+    schema: 1,
+    agent: "pi",
+    backend: pane.backend,
+    pane_id: pane.paneId,
+    pane_key: pane.paneKey,
+    tmux_session_name: pane.sessionName,
+    window_index: pane.windowIndex,
+    pane_index: pane.paneIndex,
+    cwd: session.cwd,
+    session_file: session.sessionFile,
+    session_name: session.sessionName,
+    state,
+    updated_at_ms: updatedAtMs,
+    started_at_ms: startedAtMs,
+    finished_at_ms: finishedAtMs,
+  };
+}
+
+export function serializeStatusPayload(payload: TwsStatusPayload): string {
+  return `${JSON.stringify(payload)}\n`;
+}