pi-better-harness 0.3.2 → 0.3.3

package/node_modules/pi-better-ssh/src/process-runner.ts

@@ -0,0 +1,166 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import { closeSync, mkdtempSync, openSync, rmSync, writeSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES } from "@earendil-works/pi-coding-agent";
+import type {
+  CommandOutputCapture,
+  CommandResult,
+  CommandSpec,
+  RemoteRunner,
+  SpawnedProcess,
+} from "./shared-ssh-core/index.js";
+
+const DEFAULT_CAPTURE_BYTES = DEFAULT_MAX_BYTES * 2;
+
+export function createProcessRemoteRunner(): RemoteRunner {
+  return {
+    spawn(): SpawnedProcess {
+      throw new Error("pi-better-ssh does not support detached remote processes; use bg_task_spawn with structured ssh");
+    },
+    runOnce: runProcessOnce,
+  };
+}
+
+function runProcessOnce(
+  spec: CommandSpec,
+  maxBufferBytes = DEFAULT_CAPTURE_BYTES,
+  timeoutMs?: number,
+  signal?: AbortSignal,
+): Promise<CommandResult> {
+  const argv = validateCommandSpec(spec);
+  const startedAt = Date.now();
+  const child = nodeSpawn(argv[0]!, argv.slice(1), {
+    cwd: spec.cwd,
+    env: { ...process.env, ...spec.env },
+    shell: false,
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+  });
+  const retainedBytes = Math.max(DEFAULT_CAPTURE_BYTES, Math.floor(maxBufferBytes));
+  const combined = new CommandOutputCaptureBuffer(retainedBytes);
+  const stdout = new TailBuffer(retainedBytes);
+  const stderr = new TailBuffer(retainedBytes);
+  let timedOut = false;
+  let settled = false;
+
+  child.stdout?.on("data", (chunk: Buffer) => {
+    stdout.append(chunk);
+    combined.append(chunk);
+  });
+  child.stderr?.on("data", (chunk: Buffer) => {
+    stderr.append(chunk);
+    combined.append(chunk);
+  });
+
+  return new Promise((resolve, reject) => {
+    const stopSlave = (): void => {
+      if (!settled) child.kill("SIGTERM");
+    };
+    const onAbort = (): void => stopSlave();
+    const timeout = timeoutMs === undefined ? undefined : setTimeout(() => {
+      timedOut = true;
+      stopSlave();
+    }, Math.max(1, timeoutMs));
+    timeout?.unref();
+    if (signal?.aborted) stopSlave();
+    else signal?.addEventListener("abort", onAbort, { once: true });
+
+    const finish = (): void => {
+      settled = true;
+      if (timeout) clearTimeout(timeout);
+      signal?.removeEventListener("abort", onAbort);
+    };
+    child.on("error", (error) => {
+      finish();
+      combined.discard();
+      reject(error);
+    });
+    child.on("close", (exitCode, childSignal) => {
+      finish();
+      resolve({
+        exitCode,
+        signal: childSignal,
+        stdout: stdout.text(),
+        stderr: stderr.text(),
+        startedAt,
+        endedAt: Date.now(),
+        ...(timedOut ? { timedOut: true } : {}),
+        outputCapture: combined.finish(),
+      });
+    });
+  });
+}
+
+function validateCommandSpec(spec: CommandSpec): string[] {
+  if (spec.shell !== false || !spec.argv?.[0]) {
+    throw new Error("pi-better-ssh runner requires a non-empty shell:false argv");
+  }
+  return spec.argv;
+}
+
+class TailBuffer {
+  private chunks: Buffer[] = [];
+  private bytes = 0;
+
+  constructor(private readonly maxBytes: number) {}
+
+  append(chunk: Buffer): void {
+    this.chunks.push(Buffer.from(chunk));
+    this.bytes += chunk.length;
+    while (this.bytes > this.maxBytes && this.chunks.length > 1) {
+      const removed = this.chunks.shift()!;
+      this.bytes -= removed.length;
+    }
+    if (this.bytes > this.maxBytes && this.chunks.length === 1) {
+      this.chunks[0] = this.chunks[0]!.subarray(this.bytes - this.maxBytes);
+      this.bytes = this.chunks[0]!.length;
+    }
+  }
+
+  text(): string {
+    return Buffer.concat(this.chunks).toString("utf8");
+  }
+}
+
+class CommandOutputCaptureBuffer extends TailBuffer {
+  private readonly directory = mkdtempSync(join(tmpdir(), "pi-remote-bash-"));
+  private readonly path = join(this.directory, "output.log");
+  private readonly fd = openSync(this.path, "w", 0o600);
+  private totalBytes = 0;
+  private newlineCount = 0;
+  private closed = false;
+
+  override append(chunk: Buffer): void {
+    super.append(chunk);
+    writeSync(this.fd, chunk);
+    this.totalBytes += chunk.length;
+    for (const byte of chunk) {
+      if (byte === 0x0a) this.newlineCount += 1;
+    }
+  }
+
+  finish(): CommandOutputCapture {
+    this.close();
+    const totalLines = this.newlineCount + 1;
+    const truncated = this.totalBytes > DEFAULT_MAX_BYTES || totalLines > DEFAULT_MAX_LINES;
+    if (!truncated) rmSync(this.directory, { recursive: true, force: true });
+    return {
+      output: this.text(),
+      totalBytes: this.totalBytes,
+      totalLines,
+      ...(truncated ? { fullOutputPath: this.path } : {}),
+    };
+  }
+
+  discard(): void {
+    this.close();
+    rmSync(this.directory, { recursive: true, force: true });
+  }
+
+  private close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    closeSync(this.fd);
+  }
+}

package/node_modules/pi-better-ssh/src/profile.ts

@@ -0,0 +1,132 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const SSH_PROFILE_ENTRY_TYPE = "pi-better-ssh-profile";
+
+export interface SshProfile {
+  host: string;
+  workdir?: string;
+  env?: Record<string, string>;
+}
+
+interface SessionEntryLike {
+  type?: unknown;
+  customType?: unknown;
+  data?: unknown;
+}
+
+export function defaultSshConfigPath(): string {
+  return join(homedir(), ".ssh", "config");
+}
+
+export function listSshHostAliases(configPath = defaultSshConfigPath()): string[] {
+  let config: string;
+  try {
+    config = readFileSync(configPath, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+
+  const aliases = new Set<string>();
+  for (const line of config.split(/\r?\n/)) {
+    const directive = line.trim().match(/^Host\s+(.+?)(?:\s+#.*)?$/i);
+    if (!directive) continue;
+    for (const token of directive[1]!.trim().split(/\s+/)) {
+      if (!token || token.startsWith("!") || /[*?]/.test(token)) continue;
+      aliases.add(token);
+    }
+  }
+  return [...aliases].sort((left, right) => left.localeCompare(right));
+}
+
+export function createSshProfile(
+  input: { host?: string; workdir?: string; env?: Record<string, string> },
+  aliases: readonly string[],
+  configPath = defaultSshConfigPath(),
+): SshProfile {
+  const host = input.host?.trim();
+  if (!host) throw new Error("ssh_profile use requires host (an SSH config Host alias or user@host)");
+  if (/\s/.test(host) || host.startsWith("@") || host.endsWith("@")) {
+    throw new Error("ssh_profile host must be an SSH config Host alias or user@host");
+  }
+  if (!host.includes("@") && !aliases.includes(host)) {
+    throw new Error(`ssh_profile host ${JSON.stringify(host)} is not a Host alias in ${configPath}; use a configured alias or user@host`);
+  }
+
+  const workdir = input.workdir?.trim();
+  if (input.workdir !== undefined && !workdir) {
+    throw new Error("ssh_profile workdir must not be empty");
+  }
+  const env = validateEnvironment(input.env);
+  return {
+    host,
+    ...(workdir ? { workdir } : {}),
+    ...(env ? { env } : {}),
+  };
+}
+
+export function restoreSshProfile(entries: Iterable<SessionEntryLike>): SshProfile | undefined {
+  let active: SshProfile | undefined;
+  for (const entry of entries) {
+    if (entry.type !== "custom" || entry.customType !== SSH_PROFILE_ENTRY_TYPE) continue;
+    if (!entry.data || typeof entry.data !== "object") continue;
+    const data = entry.data as { version?: unknown; active?: unknown };
+    if (data.version !== 1) continue;
+    if (data.active === null) {
+      active = undefined;
+      continue;
+    }
+    const restored = validateStoredProfile(data.active);
+    if (restored) active = restored;
+  }
+  return active;
+}
+
+export function profileStateEntry(active: SshProfile | undefined): { version: 1; active: SshProfile | null } {
+  return { version: 1, active: active ? cloneProfile(active) : null };
+}
+
+export function formatSshProfileChip(profile: SshProfile, muxState: "up" | "down"): string {
+  return `SSH: ${profile.host}${profile.workdir ? `:${profile.workdir}` : ""} (mux ${muxState})`;
+}
+
+function validateStoredProfile(value: unknown): SshProfile | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const candidate = value as { host?: unknown; workdir?: unknown; env?: unknown };
+  if (typeof candidate.host !== "string" || !candidate.host.trim() || /\s/.test(candidate.host)) return undefined;
+  if (candidate.workdir !== undefined && (typeof candidate.workdir !== "string" || !candidate.workdir.trim())) return undefined;
+  const env = validateEnvironment(candidate.env, false);
+  if (candidate.env !== undefined && !env) return undefined;
+  return {
+    host: candidate.host,
+    ...(typeof candidate.workdir === "string" ? { workdir: candidate.workdir } : {}),
+    ...(env ? { env } : {}),
+  };
+}
+
+function validateEnvironment(value: unknown, throwOnInvalid = true): Record<string, string> | undefined {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    if (throwOnInvalid) throw new Error("ssh_profile env must be a string map");
+    return undefined;
+  }
+  const env: Record<string, string> = {};
+  for (const [name, entry] of Object.entries(value)) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || typeof entry !== "string") {
+      if (throwOnInvalid) throw new Error(`ssh_profile env contains an invalid variable ${JSON.stringify(name)}`);
+      return undefined;
+    }
+    env[name] = entry;
+  }
+  return env;
+}
+
+function cloneProfile(profile: SshProfile): SshProfile {
+  return {
+    host: profile.host,
+    ...(profile.workdir ? { workdir: profile.workdir } : {}),
+    ...(profile.env ? { env: { ...profile.env } } : {}),
+  };
+}

package/node_modules/pi-better-ssh/src/remote-bash.ts

@@ -0,0 +1,184 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  truncateTail,
+} from "@earendil-works/pi-coding-agent";
+import type { TruncationResult } from "@earendil-works/pi-coding-agent";
+import {
+  createSshMuxController,
+  resolveSshCommand,
+  wrapRemoteBashCommand,
+} from "./shared-ssh-core/index.js";
+import type { RemoteRunner, SshConnectionParams } from "./shared-ssh-core/index.js";
+import type { SshMuxRegistry } from "./mux-registry.js";
+
+const MAX_TIMEOUT_MS = 2_147_483_647;
+const REMOTE_CAPTURE_BYTES = DEFAULT_MAX_BYTES * 2;
+
+export interface RemoteBashParams {
+  command: string;
+  host?: string;
+  workdir?: string;
+  timeout?: number;
+  env?: Record<string, string>;
+  user?: string;
+  port?: number;
+  identity_file?: string;
+  jump?: string;
+  options?: Record<string, string>;
+}
+
+export interface RemoteBashDependencies {
+  runner: RemoteRunner;
+  sessionScope: string;
+  controlPathRoot?: string;
+  muxRegistry?: Pick<SshMuxRegistry, "controllerFor">;
+  activeProfile?: {
+    host: string;
+    workdir?: string;
+    env?: Record<string, string>;
+  };
+}
+
+export interface RemoteBashResult {
+  output: string;
+  exitCode: number | undefined;
+  cancelled: boolean;
+  timedOut: boolean;
+  truncated: boolean;
+  target: string;
+  workdir?: string;
+  mux: {
+    state: "up";
+    reused: boolean;
+  };
+  truncation?: TruncationResult;
+  fullOutputPath?: string;
+}
+
+export async function executeRemoteBash(
+  params: RemoteBashParams,
+  dependencies: RemoteBashDependencies,
+  signal?: AbortSignal,
+): Promise<RemoteBashResult> {
+  const effectiveParams = applyActiveProfile(params, dependencies.activeProfile);
+  const ssh = resolveRemoteBashConnection(effectiveParams);
+  const timeoutMs = resolveTimeoutMs(effectiveParams.timeout);
+  const remoteCommand = wrapRemoteBashCommand({
+    command: effectiveParams.command,
+    workdir: effectiveParams.workdir,
+    env: effectiveParams.env,
+  });
+  const resolved = resolveSshCommand({ command: remoteCommand, ssh });
+  const mux = dependencies.muxRegistry
+    ? dependencies.muxRegistry.controllerFor(resolved, dependencies.sessionScope)
+    : createSshMuxController({
+      ...resolved,
+      runner: dependencies.runner,
+      sessionScope: dependencies.sessionScope,
+      ...(dependencies.controlPathRoot ? { controlPathRoot: dependencies.controlPathRoot } : {}),
+    });
+  const muxState = await mux.ensure();
+  const commandResult = await dependencies.runner.runOnce(
+    mux.withMux(resolved.commandSpec),
+    REMOTE_CAPTURE_BYTES,
+    timeoutMs,
+    signal,
+  );
+  const combinedOutput = commandResult.outputCapture?.output ?? `${commandResult.stdout}${commandResult.stderr}`;
+  const retainedTruncation = truncateTail(combinedOutput, {
+    maxLines: DEFAULT_MAX_LINES,
+    maxBytes: DEFAULT_MAX_BYTES,
+  });
+  const truncation = commandResult.outputCapture
+    ? {
+      ...retainedTruncation,
+      totalBytes: commandResult.outputCapture.totalBytes,
+      totalLines: commandResult.outputCapture.totalLines,
+    }
+    : retainedTruncation;
+  const cancelled = commandResult.timedOut === true || signal?.aborted === true;
+  const fullOutputPath = truncation.truncated
+    ? commandResult.outputCapture?.fullOutputPath ?? persistFullOutput(`${commandResult.stdout}${commandResult.stderr}`)
+    : undefined;
+
+  return {
+    output: truncation.content,
+    exitCode: cancelled ? undefined : commandResult.exitCode ?? undefined,
+    cancelled,
+    timedOut: commandResult.timedOut === true,
+    truncated: truncation.truncated,
+    target: resolved.identity.target,
+    ...(effectiveParams.workdir !== undefined ? { workdir: effectiveParams.workdir } : {}),
+    mux: { state: "up", reused: muxState.reused },
+    ...(truncation.truncated ? { truncation } : {}),
+    ...(fullOutputPath ? { fullOutputPath } : {}),
+  };
+}
+
+function applyActiveProfile(
+  params: RemoteBashParams,
+  profile: RemoteBashDependencies["activeProfile"],
+): RemoteBashParams {
+  if (!profile) return params;
+  const env = profile.env || params.env
+    ? { ...profile.env, ...params.env }
+    : undefined;
+  return {
+    ...params,
+    host: params.host ?? profile.host,
+    workdir: params.workdir ?? profile.workdir,
+    ...(env ? { env } : {}),
+  };
+}
+
+export function resolveRemoteBashConnection(params: RemoteBashParams): SshConnectionParams {
+  const rawHost = params.host?.trim();
+  if (!rawHost) {
+    throw new Error("remote_bash requires host (an SSH Host alias or user@host); no active SSH profile is available");
+  }
+  if (/\s/.test(rawHost)) {
+    throw new Error("remote_bash host must not contain whitespace");
+  }
+
+  const separator = rawHost.lastIndexOf("@");
+  const embeddedUser = separator > 0 ? rawHost.slice(0, separator) : undefined;
+  const host = separator > 0 ? rawHost.slice(separator + 1) : rawHost;
+  if (!host || (separator === 0)) {
+    throw new Error("remote_bash host must be an SSH Host alias or user@host");
+  }
+  if (embeddedUser && params.user && embeddedUser !== params.user) {
+    throw new Error(`remote_bash user ${JSON.stringify(params.user)} conflicts with host user ${JSON.stringify(embeddedUser)}`);
+  }
+
+  return {
+    host,
+    ...(params.user || embeddedUser ? { user: params.user ?? embeddedUser } : {}),
+    ...(params.port !== undefined ? { port: params.port } : {}),
+    ...(params.identity_file !== undefined ? { identity_file: params.identity_file } : {}),
+    ...(params.jump !== undefined ? { jump: params.jump } : {}),
+    ...(params.options !== undefined ? { options: params.options } : {}),
+  };
+}
+
+function resolveTimeoutMs(timeoutSeconds: number | undefined): number | undefined {
+  if (timeoutSeconds === undefined) return undefined;
+  if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0) {
+    throw new Error("remote_bash timeout must be a positive finite number of seconds");
+  }
+  const timeoutMs = timeoutSeconds * 1000;
+  if (timeoutMs > MAX_TIMEOUT_MS) {
+    throw new Error(`remote_bash timeout must not exceed ${MAX_TIMEOUT_MS / 1000} seconds`);
+  }
+  return timeoutMs;
+}
+
+function persistFullOutput(output: string): string {
+  const directory = mkdtempSync(join(tmpdir(), "pi-remote-bash-"));
+  const path = join(directory, "output.log");
+  writeFileSync(path, output, "utf8");
+  return path;
+}