pi-remote-control 1.0.0

package/src/active-session-registry.ts

@@ -0,0 +1,205 @@
+import { readSessionTranscriptMessages } from "./session-transcript.js";
+import { DEFAULT_TRANSCRIPT_PAGE_LIMIT, olderTranscriptPage, recentTranscriptWindow, type TranscriptPage } from "./transcript-pagination.js";
+import type { RuntimeStatus, ToolCallStatus } from "./types.js";
+
+export type ActiveProject = {
+  id: string;
+  name: string;
+  path: string;
+};
+
+export type ActiveSessionRegistration = {
+  id: string;
+  piSessionId: string;
+  project: ActiveProject;
+  sessionFile: string;
+  name?: string;
+  pid: number;
+  messageCount: number;
+  isStreaming: boolean;
+  updatedAt: string;
+  runtimeStatus?: RuntimeStatus;
+  entries?: unknown[];
+};
+
+export type ActiveSessionSummary = {
+  id: string;
+  piSessionId: string;
+  projectId: string;
+  name: string | null;
+  path: string;
+  updatedAt: string;
+  messageCount: number;
+  isActive: boolean;
+};
+
+export type RemoteTuiCommand =
+  | { type: "remote_prompt"; requestId: string; text: string; streamingBehavior?: "steer" | "followUp" | null }
+  | { type: "remote_abort"; requestId: string }
+  | { type: "remote_compact"; requestId: string };
+
+export type ActiveSessionState = TranscriptPage & {
+  session: ActiveSessionSummary;
+  tools: ToolCallStatus[];
+  isStreaming: boolean;
+  pendingMessageCount: number;
+  runtimeStatus: RuntimeStatus | null;
+};
+
+export type ActiveSessionRegistry = {
+  registerSession(session: ActiveSessionRegistration): ActiveSessionSummary;
+  unregisterSession(sessionId: string): boolean;
+  touchSession(sessionId: string): boolean;
+  pruneInactiveSessions(): string[];
+  listProjects(): ActiveProject[];
+  listProjectSessions(projectId: string): ActiveSessionSummary[];
+  getSessionState(sessionId: string, options?: { messageLimit?: number }): ActiveSessionState | undefined;
+  getSessionMessages(sessionId: string, beforeCursor: string, options?: { limit?: number }): TranscriptPage | undefined;
+  updateRuntimeStatus(sessionId: string, status: RuntimeStatus): boolean;
+  enqueueCommand(sessionId: string, command: RemoteTuiCommand): boolean;
+  takeCommands(sessionId: string): RemoteTuiCommand[];
+};
+
+export type ActiveSessionRegistryOptions = {
+  now?: () => number;
+  staleSessionTimeoutMs?: number;
+  isProcessRunning?: (pid: number) => boolean;
+};
+
+export const DEFAULT_ACTIVE_SESSION_STALE_TIMEOUT_MS = 5_000;
+
+type StoredActiveSession = ActiveSessionRegistration & {
+  summary: ActiveSessionSummary;
+  tools: ToolCallStatus[];
+  pendingMessageCount: number;
+  commands: RemoteTuiCommand[];
+  lastSeenAtMs: number;
+};
+
+export function createActiveSessionRegistry(options: ActiveSessionRegistryOptions = {}): ActiveSessionRegistry {
+  const sessions = new Map<string, StoredActiveSession>();
+  const now = options.now ?? Date.now;
+  const staleSessionTimeoutMs = options.staleSessionTimeoutMs ?? DEFAULT_ACTIVE_SESSION_STALE_TIMEOUT_MS;
+  const isProcessRunning = options.isProcessRunning;
+
+  const pruneInactiveSessions = (): string[] => {
+    const cutoff = now() - staleSessionTimeoutMs;
+    const removed: string[] = [];
+    for (const [sessionId, session] of sessions) {
+      if (session.lastSeenAtMs <= cutoff || (isProcessRunning ? !isProcessRunning(session.pid) : false)) {
+        sessions.delete(sessionId);
+        removed.push(sessionId);
+      }
+    }
+    return removed;
+  };
+
+  return {
+    registerSession(session) {
+      const summary = toSummary(session);
+      sessions.set(session.id, {
+        ...session,
+        summary,
+        tools: [],
+        pendingMessageCount: 0,
+        commands: [],
+        lastSeenAtMs: now(),
+      });
+      return summary;
+    },
+
+    unregisterSession(sessionId) {
+      return sessions.delete(sessionId);
+    },
+
+    touchSession(sessionId) {
+      pruneInactiveSessions();
+      const session = sessions.get(sessionId);
+      if (!session) return false;
+      session.lastSeenAtMs = now();
+      return true;
+    },
+
+    pruneInactiveSessions,
+
+    listProjects() {
+      pruneInactiveSessions();
+      const projects = new Map<string, ActiveProject>();
+      for (const session of sessions.values()) projects.set(session.project.id, session.project);
+      return [...projects.values()].sort((left, right) => left.name.localeCompare(right.name));
+    },
+
+    listProjectSessions(projectId) {
+      pruneInactiveSessions();
+      return [...sessions.values()]
+        .filter((session) => session.project.id === projectId)
+        .map((session) => session.summary)
+        .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+    },
+
+    getSessionState(sessionId, options) {
+      pruneInactiveSessions();
+      const session = sessions.get(sessionId);
+      if (!session) return undefined;
+      const messages = readSessionTranscriptMessages(session.sessionFile);
+      return {
+        session: {
+          ...session.summary,
+          messageCount: messages.length,
+          updatedAt: messages.at(-1)?.createdAt ?? session.summary.updatedAt,
+        },
+        ...recentTranscriptWindow(messages, options?.messageLimit ?? DEFAULT_TRANSCRIPT_PAGE_LIMIT),
+        tools: session.tools,
+        isStreaming: session.isStreaming,
+        pendingMessageCount: session.pendingMessageCount,
+        runtimeStatus: session.runtimeStatus ?? null,
+      };
+    },
+
+    getSessionMessages(sessionId, beforeCursor, options) {
+      pruneInactiveSessions();
+      const session = sessions.get(sessionId);
+      if (!session) return undefined;
+      return olderTranscriptPage(readSessionTranscriptMessages(session.sessionFile), beforeCursor, options?.limit ?? DEFAULT_TRANSCRIPT_PAGE_LIMIT);
+    },
+
+    updateRuntimeStatus(sessionId, status) {
+      pruneInactiveSessions();
+      const session = sessions.get(sessionId);
+      if (!session) return false;
+      if (JSON.stringify(session.runtimeStatus ?? null) === JSON.stringify(status)) return false;
+      session.runtimeStatus = status;
+      return true;
+    },
+
+    enqueueCommand(sessionId, command) {
+      pruneInactiveSessions();
+      const session = sessions.get(sessionId);
+      if (!session) return false;
+      session.commands.push(command);
+      return true;
+    },
+
+    takeCommands(sessionId) {
+      pruneInactiveSessions();
+      const session = sessions.get(sessionId);
+      if (!session) return [];
+      const commands = session.commands;
+      session.commands = [];
+      return commands;
+    },
+  };
+}
+
+function toSummary(session: ActiveSessionRegistration): ActiveSessionSummary {
+  return {
+    id: session.id,
+    piSessionId: session.piSessionId,
+    projectId: session.project.id,
+    name: session.name ?? null,
+    path: session.sessionFile,
+    updatedAt: session.updatedAt,
+    messageCount: session.messageCount,
+    isActive: true,
+  };
+}

package/src/auth/pairing.ts

@@ -0,0 +1,30 @@
+import { randomInt, createHash, timingSafeEqual } from "node:crypto";
+import type { PairingCode } from "../types.js";
+
+export type CreatedPairingCode = PairingCode & {
+  rawCode: string;
+};
+
+export function createPairingCode(now: Date, ttlMs: number): CreatedPairingCode {
+  const rawCode = randomInt(0, 1_000_000).toString().padStart(6, "0");
+  return {
+    id: `pair_${createHash("sha256").update(`${rawCode}:${now.toISOString()}`).digest("hex").slice(0, 16)}`,
+    rawCode,
+    codeHash: createHash("sha256").update(rawCode).digest("hex"),
+    createdAt: now.toISOString(),
+    expiresAt: new Date(now.getTime() + ttlMs).toISOString(),
+  };
+}
+
+export function hashPairingCode(rawCode: string): string {
+  return createHash("sha256").update(rawCode).digest("hex");
+}
+
+export function canClaimPairingCode(pairingCode: PairingCode, rawCode: string, now: Date): boolean {
+  if (pairingCode.consumedAt) return false;
+  if (Date.parse(pairingCode.expiresAt) <= now.getTime()) return false;
+
+  const expected = Buffer.from(pairingCode.codeHash);
+  const actual = Buffer.from(hashPairingCode(rawCode));
+  return expected.length === actual.length && timingSafeEqual(expected, actual);
+}

package/src/auth/tokens.ts

@@ -0,0 +1,30 @@
+import { randomBytes, scrypt, scryptSync, timingSafeEqual } from "node:crypto";
+import { promisify } from "node:util";
+
+export type IssuedDeviceToken = {
+  rawToken: string;
+  tokenHash: string;
+};
+
+export function issueDeviceToken(): IssuedDeviceToken {
+  const rawToken = `prd_${randomBytes(32).toString("base64url")}`;
+  const salt = randomBytes(16).toString("base64url");
+  const derived = scryptSync(rawToken, salt, 32).toString("base64url");
+  return { rawToken, tokenHash: `scrypt:${salt}:${derived}` };
+}
+
+export async function hashDeviceToken(rawToken: string, salt = randomBytes(16).toString("base64url")): Promise<string> {
+  const derive = promisify(scrypt) as (password: string, salt: string, keylen: number) => Promise<Buffer>;
+  const derived = await derive(rawToken, salt, 32);
+  return `scrypt:${salt}:${derived.toString("base64url")}`;
+}
+
+export async function verifyDeviceToken(rawToken: string, encodedHash: string): Promise<boolean> {
+  const [algorithm, salt, expected] = encodedHash.split(":");
+  if (algorithm !== "scrypt" || !salt || !expected) return false;
+
+  const actual = await hashDeviceToken(rawToken, salt);
+  const actualKey = Buffer.from(actual.split(":")[2] ?? "");
+  const expectedKey = Buffer.from(expected);
+  return actualKey.length === expectedKey.length && timingSafeEqual(actualKey, expectedKey);
+}

package/src/cli-runner.cjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+const { createJiti } = require("jiti");
+
+const jiti = createJiti(__filename);
+const { main } = jiti("./cli.ts");
+
+main(process.argv.slice(2)).then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  },
+);

package/src/cli.ts

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+import { readFile, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createActiveSessionRegistry } from "./active-session-registry.js";
+import { defaultDaemonConfig, loadDaemonConfig, saveDaemonConfig } from "./config.js";
+import { acquireDaemonLock, type DaemonLock } from "./lock.js";
+import type { DaemonStore } from "./persistence/daemon-store.js";
+import { ensureDaemonStateDir, getDaemonStateDir } from "./paths.js";
+import { buildPairingLink } from "./pairing-link.js";
+import { formatPairingDisplay } from "./qr.js";
+import { startDaemonServer, type DaemonServer, type StartServerOptions } from "./server/http.js";
+import type { DaemonConfig } from "./types.js";
+
+export type CliDependencies = {
+  getStateDir?: (options?: { env?: NodeJS.ProcessEnv }) => string;
+  ensureStateDir?: (stateDir: string) => Promise<void>;
+  loadConfig?: (stateDir: string) => Promise<DaemonConfig>;
+  saveConfig?: (stateDir: string, config: DaemonConfig) => Promise<void>;
+  startServer?: (options: StartServerOptions) => Promise<DaemonServer>;
+  openStore?: (stateDir: string) => DaemonStore | Promise<DaemonStore>;
+  acquireLock?: (stateDir: string) => Promise<DaemonLock | undefined>;
+  waitForShutdown?: () => Promise<void>;
+  readTextFile?: (path: string) => Promise<string>;
+  removeFile?: (path: string) => Promise<void>;
+  isProcessRunning?: (pid: number) => boolean;
+  sendSignal?: (pid: number, signal: NodeJS.Signals) => void;
+  getPiVersion?: () => string | Promise<string>;
+  writeLine?: (line: string) => void;
+  env?: NodeJS.ProcessEnv;
+};
+
+export async function main(argv = process.argv.slice(2), deps: CliDependencies = {}): Promise<number> {
+  const command = argv[0];
+  const env = deps.env ?? process.env;
+  if (command === "status") return statusCommand(argv.slice(1), deps, env);
+  if (command === "stop") return stopCommand(argv.slice(1), deps, env);
+  if (command === "pair") return pairCommand(argv.slice(1), deps, env);
+  if (command !== "start") {
+    (deps.writeLine ?? console.log)("Usage: pi-remote-control start|stop|status|pair [options]");
+    return command === "--help" || command === "-h" ? 0 : 1;
+  }
+
+  const parsed = parseStartArgs(argv.slice(1));
+  const stateDir = parsed.stateDir ?? (deps.getStateDir ?? getDaemonStateDir)({ env });
+  await (deps.ensureStateDir ?? ensureDaemonStateDir)(stateDir);
+
+  const lock = await (deps.acquireLock ?? acquireDaemonLock)(stateDir);
+  if (!lock) {
+    (deps.writeLine ?? console.log)("pi-remote-control is already running");
+    return 1;
+  }
+
+  const loadedConfig = await (deps.loadConfig ?? loadDaemonConfig)(stateDir).catch(async (error) => {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      const config = defaultDaemonConfig();
+      await (deps.saveConfig ?? saveDaemonConfig)(stateDir, config);
+      return config;
+    }
+    throw error;
+  });
+  await (deps.saveConfig ?? saveDaemonConfig)(stateDir, loadedConfig);
+  const config = { ...loadedConfig, bindAddress: parsed.bindAddress ?? loadedConfig.bindAddress };
+  const devToken = env.PI_REMOTE_CONTROL_DEV_TOKEN;
+  const store = await (deps.openStore ?? openStore)(stateDir);
+  const piVersion = await (deps.getPiVersion ?? readInstalledPiVersion)();
+  const server = await (deps.startServer ?? startDaemonServer)({
+    stateDir,
+    config,
+    piVersion,
+    authenticateToken: devToken ? (token) => token === devToken || store.authenticateToken(token) : (token) => store.authenticateToken(token),
+    activeSessions: createActiveSessionRegistry({ isProcessRunning }),
+    pairService: {
+      createPairingCode: () => store.createPairingCode(new Date(), 5 * 60_000),
+      claimPairingCode: async (request) => {
+        const claimed = await store.claimPairingCode(request.pairCode, request.deviceName, new Date());
+        if (!claimed) throw new Error("Invalid or expired pairing code");
+        return claimed;
+      },
+    },
+  });
+  (deps.writeLine ?? console.log)(`pi-remote-control listening on http://${server.address}`);
+  if (devToken) (deps.writeLine ?? console.log)("dev token authentication is enabled");
+
+  await (deps.waitForShutdown ?? waitForInterrupt)();
+  await server.close();
+  store.close();
+  await lock.release();
+  return 0;
+}
+
+async function pairCommand(args: string[], deps: CliDependencies, env: NodeJS.ProcessEnv): Promise<number> {
+  const writeLine = deps.writeLine ?? console.log;
+  const stateDir = parseStateDirArg(args) ?? (deps.getStateDir ?? getDaemonStateDir)({ env });
+  await (deps.ensureStateDir ?? ensureDaemonStateDir)(stateDir);
+  const config = await (deps.loadConfig ?? loadDaemonConfig)(stateDir);
+  const advertisedBaseUrl = parseAdvertisedBaseUrlArg(args) ?? env.PI_REMOTE_CONTROL_ADVERTISED_BASE_URL ?? config.advertisedBaseUrl ?? env.PI_REMOTE_CONTROL_URL;
+  if (!advertisedBaseUrl) {
+    writeLine("advertisedBaseUrl is required for QR pairing.");
+    writeLine("Set ~/.pi/remote-control/config.json or PI_REMOTE_CONTROL_ADVERTISED_BASE_URL to an iOS-reachable URL.");
+    writeLine("Example: https://macbook.tailnet.ts.net:17373");
+    return 1;
+  }
+
+  const store = await (deps.openStore ?? openStore)(stateDir);
+  try {
+    const result = await store.createPairingCode(new Date(), 5 * 60_000);
+    const pairingLink = buildPairingLink({
+      advertisedBaseUrl,
+      pairCode: result.pairCode,
+      expiresAt: result.expiresAt,
+    });
+    for (const line of formatPairingDisplay({ expiresAt: result.expiresAt, pairingLink })) {
+      writeLine(line);
+    }
+    return 0;
+  } finally {
+    store.close();
+  }
+}
+
+async function stopCommand(args: string[], deps: CliDependencies, env: NodeJS.ProcessEnv): Promise<number> {
+  const stateDir = parseStateDirArg(args) ?? (deps.getStateDir ?? getDaemonStateDir)({ env });
+  const writeLine = deps.writeLine ?? console.log;
+  const readTextFile = deps.readTextFile ?? ((path: string) => readFile(path, "utf8"));
+
+  const lockFile = join(stateDir, "daemon.lock");
+  try {
+    const pid = Number.parseInt((await readTextFile(lockFile)).trim(), 10);
+    try {
+      (deps.sendSignal ?? process.kill)(pid, "SIGTERM");
+      writeLine(`pi-remote-control stop requested (pid ${pid})`);
+    } catch (error) {
+      if (!(error && typeof error === "object" && "code" in error && error.code === "ESRCH")) throw error;
+      writeLine(`pi-remote-control stale lock removed (pid ${pid})`);
+    }
+    await (deps.removeFile ?? ((path: string) => rm(path, { force: true })))(lockFile);
+    return 0;
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      writeLine("pi-remote-control is not running");
+      return 1;
+    }
+    throw error;
+  }
+}
+
+async function statusCommand(args: string[], deps: CliDependencies, env: NodeJS.ProcessEnv): Promise<number> {
+  const stateDir = parseStateDirArg(args) ?? (deps.getStateDir ?? getDaemonStateDir)({ env });
+  const writeLine = deps.writeLine ?? console.log;
+  const readTextFile = deps.readTextFile ?? ((path: string) => readFile(path, "utf8"));
+
+  const lockFile = join(stateDir, "daemon.lock");
+  try {
+    const pid = Number.parseInt((await readTextFile(lockFile)).trim(), 10);
+    const running = (deps.isProcessRunning ?? isProcessRunning)(pid);
+    if (running) {
+      writeLine(`pi-remote-control is running (pid ${pid})`);
+      return 0;
+    }
+
+    await (deps.removeFile ?? ((path: string) => rm(path, { force: true })))(lockFile);
+    writeLine(`pi-remote-control is stopped (stale lock removed, pid ${pid})`);
+    return 1;
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      writeLine("pi-remote-control is stopped");
+      return 1;
+    }
+    throw error;
+  }
+}
+
+function parseAdvertisedBaseUrlArg(args: string[]): string | undefined {
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === "--advertised-base-url") return args[index + 1];
+  }
+  return undefined;
+}
+
+async function openStore(stateDir: string): Promise<DaemonStore> {
+  const { openDaemonStore } = await import("./persistence/daemon-store.js");
+  return openDaemonStore(stateDir);
+}
+
+export async function readInstalledPiVersion(): Promise<string> {
+  try {
+    let directory = dirname(fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent")));
+    while (true) {
+      const packageJsonPath = join(directory, "package.json");
+      try {
+        const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8")) as { name?: unknown; version?: unknown };
+        if (packageJson.name === "@earendil-works/pi-coding-agent" && typeof packageJson.version === "string") return packageJson.version;
+      } catch (error) {
+        if (!isNodeErrorCode(error, "ENOENT")) return "unknown";
+      }
+      const parent = dirname(directory);
+      if (parent === directory) return "unknown";
+      directory = parent;
+    }
+  } catch {
+    return "unknown";
+  }
+}
+
+function parseStateDirArg(args: string[]): string | undefined {
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === "--state-dir") return args[index + 1];
+  }
+  return undefined;
+}
+
+function isProcessRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isNodeErrorCode(error: unknown, code: string): boolean {
+  return Boolean(error && typeof error === "object" && "code" in error && error.code === code);
+}
+
+function parseStartArgs(args: string[]): { stateDir?: string; bindAddress?: string } {
+  const parsed: { stateDir?: string; bindAddress?: string } = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--state-dir") parsed.stateDir = args[++index];
+    else if (arg === "--bind") parsed.bindAddress = args[++index];
+    else throw new Error(`Unknown start option: ${arg}`);
+  }
+  return parsed;
+}
+
+async function waitForInterrupt(): Promise<void> {
+  await new Promise<void>((resolve) => {
+    process.once("SIGINT", resolve);
+    process.once("SIGTERM", resolve);
+  });
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().then(
+    (code) => {
+      process.exitCode = code;
+    },
+    (error) => {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exitCode = 1;
+    },
+  );
+}

package/src/config.ts

@@ -0,0 +1,26 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { DaemonConfig } from "./types.js";
+
+export const DEFAULT_BIND_ADDRESS = "127.0.0.1:17373";
+
+export function defaultDaemonConfig(): DaemonConfig {
+  return { bindAddress: DEFAULT_BIND_ADDRESS };
+}
+
+export async function loadDaemonConfig(stateDir: string): Promise<DaemonConfig> {
+  try {
+    const content = await readFile(join(stateDir, "config.json"), "utf8");
+    return JSON.parse(content) as DaemonConfig;
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return defaultDaemonConfig();
+    }
+    throw error;
+  }
+}
+
+export async function saveDaemonConfig(stateDir: string, config: DaemonConfig): Promise<void> {
+  const content = `${JSON.stringify(config, null, 2)}\n`;
+  await writeFile(join(stateDir, "config.json"), content, { mode: 0o600 });
+}