@pensar/apex 2.5.0 → 2.6.1-canary.0cc77dcc

package/src/core/whitebox/jobSupervisor.ts

@@ -0,0 +1,264 @@
+import type { createWhiteboxJobKernel } from "./jobKernel";
+import type { WhiteboxJobRecord } from "./types";
+
+export type JobRequest = {
+  operation: "start" | "poll" | "stop" | "read" | "supervise";
+  root: string;
+  codebaseRoot: string;
+  sessionId: string;
+  id?: string;
+  command?: string;
+  cwd?: string;
+  timeoutSeconds?: number;
+  name?: string;
+  requestId?: string;
+};
+
+// Serialized together with the kernel; no external runtime closures or installed paths.
+export async function runWhiteboxJobOperation(
+  load: NodeJS.Require,
+  factory: typeof createWhiteboxJobKernel,
+  input: JobRequest,
+): Promise<unknown> {
+  const fs = load("node:fs") as typeof import("node:fs");
+  const path = load("node:path") as typeof import("node:path");
+  const crypto = load("node:crypto") as typeof import("node:crypto");
+  const { spawn } = load(
+    "node:child_process",
+  ) as typeof import("node:child_process");
+  const delay = (ms: number) =>
+    new Promise((resolve) => setTimeout(resolve, ms));
+  const digest = (value: string) =>
+    crypto.createHash("sha256").update(value).digest("hex");
+  if (
+    !input.sessionId ||
+    !path.isAbsolute(input.root) ||
+    !path.isAbsolute(input.codebaseRoot)
+  )
+    throw new Error("Invalid job owner");
+  const root = fs.realpathSync(input.root);
+  if (fs.lstatSync(path.resolve(input.root)).isSymbolicLink())
+    throw new Error("Job root must not be a symlink");
+  const codebaseRoot = fs.realpathSync(input.codebaseRoot);
+  const safeDirectory = (parent: string, name: string) => {
+    const directory = path.join(parent, name);
+    try {
+      fs.mkdirSync(directory, { mode: 0o700 });
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    }
+    const stat = fs.lstatSync(directory);
+    if (
+      !stat.isDirectory() ||
+      stat.isSymbolicLink() ||
+      fs.realpathSync(directory) !== directory
+    )
+      throw new Error("Unsafe job directory");
+    return directory;
+  };
+  const ownerDir = safeDirectory(
+    safeDirectory(root, ".pensar-whitebox-jobs"),
+    digest(input.sessionId),
+  );
+  const id =
+    input.operation === "start"
+      ? `wjob_${input.requestId ? digest(input.requestId) : crypto.randomBytes(32).toString("hex")}`
+      : input.id;
+  if (!id || !/^wjob_[a-f0-9]{64}$/.test(id)) throw new Error("Invalid job id");
+  const directory = path.join(ownerDir, id);
+  const read = (filename: string) => {
+    const fd = fs.openSync(
+      path.join(directory, filename),
+      fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW,
+    );
+    try {
+      if (!fs.fstatSync(fd).isFile()) throw new Error("Invalid job state");
+      return JSON.parse(fs.readFileSync(fd, "utf8"));
+    } finally {
+      fs.closeSync(fd);
+    }
+  };
+  const write = (filename: string, data: unknown) => {
+    const temporary = path.join(
+      directory,
+      `${filename}.${crypto.randomBytes(8).toString("hex")}`,
+    );
+    fs.writeFileSync(temporary, JSON.stringify(data), {
+      flag: "wx",
+      mode: 0o600,
+    });
+    fs.renameSync(temporary, path.join(directory, filename));
+  };
+  const exists = (filename: string) =>
+    fs.existsSync(path.join(directory, filename));
+  let created = false;
+  if (input.operation === "start") {
+    if (
+      !input.command ||
+      !input.cwd ||
+      typeof input.timeoutSeconds !== "number" ||
+      !Number.isInteger(input.timeoutSeconds) ||
+      input.timeoutSeconds < 1 ||
+      input.timeoutSeconds > 86400
+    )
+      throw new Error("Invalid job request");
+    const cwd = fs.realpathSync(input.cwd);
+    if (cwd !== codebaseRoot && !cwd.startsWith(`${codebaseRoot}${path.sep}`))
+      throw new Error("Job cwd outside owned root");
+    try {
+      fs.mkdirSync(directory, { mode: 0o700 });
+      created = true;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    }
+  } else if (!fs.existsSync(directory))
+    return input.operation === "read"
+      ? { content: "", truncated: false }
+      : null;
+  if (
+    fs.lstatSync(directory).isSymbolicLink() ||
+    fs.realpathSync(directory) !== directory
+  )
+    throw new Error("Unsafe job state path");
+  if (created)
+    write("owner.json", {
+      sessionId: input.sessionId,
+      root,
+      codebaseRoot,
+      command: input.command,
+      cwd: input.cwd,
+      timeoutSeconds: input.timeoutSeconds,
+    });
+  const owner = read("owner.json");
+  if (
+    owner.sessionId !== input.sessionId ||
+    owner.root !== root ||
+    owner.codebaseRoot !== codebaseRoot
+  )
+    throw new Error("Job owner mismatch");
+  if (
+    input.operation === "start" &&
+    (owner.command !== input.command ||
+      owner.cwd !== input.cwd ||
+      owner.timeoutSeconds !== input.timeoutSeconds)
+  )
+    throw new Error("Job request identity reused with different inputs");
+  const state = () => (exists("state.json") ? read("state.json") : undefined);
+  const wait = async (
+    accept: (value: {
+      ready: boolean;
+      drained: boolean;
+      record: WhiteboxJobRecord;
+    }) => boolean,
+    ms: number,
+  ) => {
+    const until = Date.now() + ms;
+    while (Date.now() < until) {
+      const value = state();
+      if (value && accept(value)) return value;
+      await delay(25);
+    }
+    throw new Error(
+      "Job supervisor did not acknowledge operation before deadline",
+    );
+  };
+  const requestStop = () => {
+    const fd = fs.openSync(
+      path.join(directory, "stop"),
+      fs.constants.O_CREAT | fs.constants.O_WRONLY | fs.constants.O_NOFOLLOW,
+      0o600,
+    );
+    fs.closeSync(fd);
+  };
+  if (input.operation === "start") {
+    const interrupted = () => {
+      requestStop();
+      process.exit(143);
+    };
+    process.once("SIGTERM", interrupted);
+    process.once("SIGINT", interrupted);
+    try {
+      if (created) {
+        const request = { ...input, operation: "supervise", id };
+        const source = `(${runWhiteboxJobOperation.toString()})(require, ${factory.toString()}, ${JSON.stringify(request)}).catch(error => { process.stderr.write(String(error)); process.exitCode = 1; })`;
+        const child = spawn(process.execPath, ["-e", source], {
+          cwd: root,
+          detached: true,
+          stdio: "ignore",
+        });
+        const spawned = new Promise<void>((resolve, reject) => {
+          child.once("spawn", resolve);
+          child.once("error", reject);
+        });
+        await spawned;
+        child.unref();
+      }
+      const result = await wait(
+        (value) => value.ready || value.drained,
+        process.platform === "win32" ? 30000 : 10000,
+      );
+      if (!result.ready) throw new Error("Job command failed before startup");
+      return result.record;
+    } catch (error) {
+      requestStop();
+      throw error;
+    } finally {
+      process.removeListener("SIGTERM", interrupted);
+      process.removeListener("SIGINT", interrupted);
+    }
+  }
+  if (input.operation === "supervise") {
+    if (
+      !input.command ||
+      !input.cwd ||
+      typeof input.timeoutSeconds !== "number"
+    )
+      throw new Error("Invalid supervisor request");
+    const kernel = factory(load);
+    const record = kernel.startWhiteboxJob({
+      id,
+      session: { id: input.sessionId, logsPath: directory },
+      command: input.command,
+      cwd: input.cwd,
+      timeoutSeconds: input.timeoutSeconds,
+      name: input.name,
+    });
+    let previous = "";
+    while (true) {
+      if (exists("stop")) kernel.stopWhiteboxJob(id, input.sessionId);
+      const current = kernel.pollWhiteboxJob(id, input.sessionId);
+      const lifecycle = kernel.lifecycle(id);
+      const snapshot = { record: current, ...lifecycle };
+      const serialized = JSON.stringify(snapshot);
+      if (serialized !== previous) {
+        write("state.json", snapshot);
+        previous = serialized;
+      }
+      if (lifecycle.drained) break;
+      await delay(25);
+    }
+    return record;
+  }
+  let current = state();
+  if (!current) throw new Error("Job supervisor state unavailable");
+  if (
+    current.drained &&
+    Date.now() - Date.parse(current.record.updatedAt) >
+      factory(load).pruneAfterMs
+  )
+    return input.operation === "read"
+      ? { content: "", truncated: false }
+      : null;
+  if (input.operation === "stop" && !current.drained) {
+    requestStop();
+    current = await wait((value) => value.drained, 5000);
+  }
+  if (input.operation !== "read") return current.record;
+  const logPath = current.record.logPath;
+  if (
+    path.dirname(logPath) !== path.join(directory, "whitebox") ||
+    fs.realpathSync(path.dirname(logPath)) !== path.dirname(logPath)
+  )
+    throw new Error("Unsafe job log path");
+  return factory(load).readCapturedLog(current.record, true);
+}

package/src/core/whitebox/jobs.ts

@@ -0,0 +1,21 @@
+import { createRequire } from "node:module";
+import type { SessionInfo } from "../session";
+import { createWhiteboxJobKernel } from "./jobKernel";
+import type { WhiteboxJobRecord } from "./types";
+
+const kernel = createWhiteboxJobKernel(createRequire(import.meta.url));
+
+export function startWhiteboxJob(input: {
+  session: SessionInfo;
+  command: string;
+  cwd: string;
+  timeoutSeconds: number;
+  name?: string;
+  env?: Record<string, string>;
+}): WhiteboxJobRecord {
+  return kernel.startWhiteboxJob(input);
+}
+
+export const pollWhiteboxJob = kernel.pollWhiteboxJob;
+export const stopWhiteboxJob = kernel.stopWhiteboxJob;
+export const readWhiteboxJobLog = kernel.readWhiteboxJobLog;

package/src/core/whitebox/paths.ts

@@ -0,0 +1,94 @@
+import { existsSync, realpathSync } from "node:fs";
+import { isAbsolute, normalize, relative, resolve } from "node:path";
+
+/**
+ * Repository root used for whitebox profiling, scans, and code queries.
+ * Prefer explicit `session.config.codebasePath` when set; otherwise the agent cwd.
+ */
+export function resolveWhiteboxCodebaseRoot(input: {
+  agentCwd: string;
+  codebasePath?: string;
+}): string {
+  return resolve(normalize(input.codebasePath ?? input.agentCwd));
+}
+
+/**
+ * Return true when `candidate` is lexically under `root` (after normalization).
+ * Catches `..` traversals, Windows cross-drive escapes (relative() returns an
+ * absolute path), and empty-string edge cases.
+ */
+function isUnderRoot(root: string, candidate: string): boolean {
+  const rel = relative(root, candidate);
+  if (rel === "") return true;
+  if (rel.startsWith("..") || isAbsolute(rel)) return false;
+  return true;
+}
+
+/**
+ * Resolve `subPath` (file or directory) under `root` and reject escapes.
+ * Validates both the lexical path and, when the target exists on disk, the
+ * real (symlink-resolved) path to prevent symlink-based containment bypasses.
+ */
+export function resolvePathWithinCodebaseRoot(
+  root: string,
+  subPath: string = ".",
+): string {
+  const absRoot = resolve(normalize(root));
+  const candidate = isAbsolute(subPath)
+    ? resolve(normalize(subPath))
+    : resolve(absRoot, normalize(subPath));
+
+  if (!isUnderRoot(absRoot, candidate)) {
+    throw new Error(`Path escapes codebase root: ${subPath}`);
+  }
+
+  if (existsSync(candidate)) {
+    const realCandidate = realpathSync(candidate);
+    const realRoot = realpathSync(absRoot);
+    if (!isUnderRoot(realRoot, realCandidate)) {
+      throw new Error(`Path escapes codebase root via symlink: ${subPath}`);
+    }
+  }
+
+  return candidate;
+}
+
+/**
+ * Resolve a session-relative artifact path for reading. Only
+ * `logs/whitebox/...` and `scratchpad/whitebox/...` under `session.rootPath` are allowed.
+ */
+export function resolveSessionWhiteboxArtifactPath(input: {
+  sessionRootPath: string;
+  artifactRelativePath: string;
+}): string {
+  const normalized = normalize(input.artifactRelativePath).replace(/\\/g, "/");
+  if (normalized.includes("..")) {
+    throw new Error("Invalid artifact path");
+  }
+  const posixPath = normalized.startsWith("/")
+    ? normalized.slice(1)
+    : normalized;
+  const allowed =
+    posixPath.startsWith("logs/whitebox/") ||
+    posixPath.startsWith("scratchpad/whitebox/");
+  if (!allowed) {
+    throw new Error(
+      `Artifact path must start with logs/whitebox/ or scratchpad/whitebox/: ${input.artifactRelativePath}`,
+    );
+  }
+  const resolved = resolve(input.sessionRootPath, posixPath);
+
+  if (!isUnderRoot(resolve(input.sessionRootPath), resolved)) {
+    throw new Error("Invalid artifact path");
+  }
+
+  if (existsSync(resolved)) {
+    const realResolved = realpathSync(resolved);
+    const realRoot = realpathSync(input.sessionRootPath);
+    if (!isUnderRoot(realRoot, realResolved)) {
+      throw new Error("Artifact path escapes session root via symlink");
+    }
+  }
+
+  return resolved;
+}

package/src/core/whitebox/profileTransport.ts

@@ -0,0 +1,225 @@
+import { execFile } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { promisify } from "node:util";
+import type { CommandBackend } from "../tools/backends/types";
+import { runCommandBounded } from "./boundedProcess";
+import { DEFAULT_WHITEBOX_EXCLUDED_DIRS } from "./profiles";
+import type { ToolAvailability } from "./types";
+
+const execFileAsync = promisify(execFile);
+const MAX_PROFILE_FILES = 5_000;
+const MAX_PROFILE_OUTPUT_BYTES = 2 * 1024 * 1024;
+const WALK_TIMEOUT_SECONDS = 30;
+const GIT_TIMEOUT_SECONDS = 5;
+const TOOL_DETECT_TIMEOUT_SECONDS = 2;
+const TOOL_DETECT_MAX_BYTES = 64 * 1024;
+
+/** `PerCommandShell` substitutes this sentinel for genuinely empty stdout (see `result-registry.ts`'s same strip). */
+function stripNoOutputSentinel(stdout: string): string {
+  return stdout.replace(/^\(no output\)$/, "");
+}
+
+/** `cd`'d into `rootPath` and asserts it exists and is a directory — mirrors `stat(rootPath).isDirectory()`. */
+async function assertDirectory(
+  rootPath: string,
+  command: CommandBackend | undefined,
+): Promise<void> {
+  const result = await runCommandBounded(command, ["test", "-d", "."], {
+    cwd: rootPath,
+    timeoutSeconds: GIT_TIMEOUT_SECONDS,
+    maxTotalBytes: 1_024,
+  });
+  if (result.exitCode !== 0) {
+    throw new Error(`${rootPath} is not a directory`);
+  }
+}
+
+/**
+ * Prunes excluded dirs at any depth and lists files only — symlinks match
+ * neither `-type d` nor `-type f`, so they're skipped, same as the old
+ * `Dirent`-based walk (a `Dirent` for a symlink is neither). Sorted in the C
+ * locale to match Node's `readdir()` order (libuv sorts entries), which the
+ * old recursive walk relied on implicitly.
+ */
+function buildFindCommand(): string {
+  const prune = DEFAULT_WHITEBOX_EXCLUDED_DIRS.map(
+    (dir) => `-name '${dir}'`,
+  ).join(" -o ");
+  return `find . -mindepth 1 \\( -type d \\( ${prune} \\) -prune \\) -o -type f -print | LC_ALL=C sort`;
+}
+
+function shouldSkipDir(name: string): boolean {
+  return DEFAULT_WHITEBOX_EXCLUDED_DIRS.includes(name);
+}
+
+async function walkFiles(
+  rootPath: string,
+  command?: CommandBackend,
+): Promise<string[]> {
+  if (command) {
+    const result = await runCommandBounded(
+      command,
+      ["bash", "-c", buildFindCommand()],
+      {
+        cwd: rootPath,
+        timeoutSeconds: WALK_TIMEOUT_SECONDS,
+        maxTotalBytes: MAX_PROFILE_OUTPUT_BYTES,
+      },
+    );
+    const stdout = stripNoOutputSentinel(result.stdout);
+    if (!stdout) return [];
+    return stdout
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => line.replace(/^\.\//, ""))
+      .slice(0, MAX_PROFILE_FILES);
+  }
+  const files: string[] = [];
+  const absRoot = resolve(rootPath);
+
+  function isWithinRoot(path: string): boolean {
+    try {
+      const real = realpathSync(path);
+      return real === absRoot || real.startsWith(`${absRoot}/`);
+    } catch {
+      return false;
+    }
+  }
+
+  async function walk(current: string): Promise<void> {
+    if (files.length >= MAX_PROFILE_FILES) return;
+    let entries: import("node:fs").Dirent[];
+    try {
+      entries = await readdir(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (files.length >= MAX_PROFILE_FILES) return;
+      const fullPath = join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (shouldSkipDir(entry.name)) continue;
+        if (entry.isSymbolicLink() && !isWithinRoot(fullPath)) continue;
+        await walk(fullPath);
+        continue;
+      }
+      if (entry.isFile()) {
+        files.push(relative(rootPath, fullPath));
+      }
+    }
+  }
+
+  await walk(rootPath);
+  return files;
+}
+
+async function readPackageJson(
+  rootPath: string,
+  command?: CommandBackend,
+): Promise<string | undefined> {
+  let raw: string;
+  if (command) {
+    const result = await runCommandBounded(command, ["cat", "package.json"], {
+      cwd: rootPath,
+      timeoutSeconds: GIT_TIMEOUT_SECONDS,
+      maxTotalBytes: MAX_PROFILE_OUTPUT_BYTES,
+    });
+    raw = stripNoOutputSentinel(result.stdout);
+    if (result.exitCode !== 0 || !raw.trim()) {
+      return undefined;
+    }
+  } else {
+    const packageJsonPath = join(rootPath, "package.json");
+    if (!existsSync(packageJsonPath)) {
+      return undefined;
+    }
+    try {
+      raw = await readFile(packageJsonPath, "utf-8");
+    } catch {
+      return undefined;
+    }
+  }
+
+  return raw;
+}
+
+async function runGit(
+  rootPath: string,
+  args: string[],
+  command?: CommandBackend,
+): Promise<string | undefined> {
+  if (command) {
+    const result = await runCommandBounded(command, ["git", ...args], {
+      cwd: rootPath,
+      timeoutSeconds: GIT_TIMEOUT_SECONDS,
+      maxTotalBytes: MAX_PROFILE_OUTPUT_BYTES,
+    });
+    return result.exitCode === 0
+      ? stripNoOutputSentinel(result.stdout).trim()
+      : undefined;
+  }
+  try {
+    const { stdout } = await execFileAsync("git", args, {
+      cwd: rootPath,
+      timeout: 5_000,
+      maxBuffer: 1024 * 1024,
+    });
+    return String(stdout).trim();
+  } catch {
+    return undefined;
+  }
+}
+
+async function detectTool(
+  name: string,
+  rootPath: string,
+  command?: CommandBackend,
+): Promise<ToolAvailability> {
+  if (command) {
+    const result = await runCommandBounded(command, ["which", name], {
+      cwd: rootPath,
+      timeoutSeconds: TOOL_DETECT_TIMEOUT_SECONDS,
+      maxTotalBytes: TOOL_DETECT_MAX_BYTES,
+    });
+    const path = stripNoOutputSentinel(result.stdout).trim();
+    return result.exitCode === 0 && path
+      ? { name, available: true, path }
+      : { name, available: false };
+  }
+  const cmd = process.platform === "win32" ? "where" : "which";
+  try {
+    const { stdout } = await execFileAsync(cmd, [name], {
+      timeout: 2_000,
+      maxBuffer: 1024 * 64,
+    });
+    return { name, available: true, path: String(stdout).trim() };
+  } catch {
+    return { name, available: false };
+  }
+}
+
+export interface RepoProfileIO {
+  assertDirectory(rootPath: string): Promise<void>;
+  walkFiles(rootPath: string): Promise<string[]>;
+  readPackageJson(rootPath: string): Promise<string | undefined>;
+  runGit(rootPath: string, args: string[]): Promise<string | undefined>;
+  detectTool(name: string, rootPath: string): Promise<ToolAvailability>;
+}
+
+export function createRepoProfileIO(command?: CommandBackend): RepoProfileIO {
+  return {
+    async assertDirectory(rootPath) {
+      if (command) return assertDirectory(rootPath, command);
+      const rootStat = await stat(rootPath);
+      if (!rootStat.isDirectory())
+        throw new Error(`${rootPath} is not a directory`);
+    },
+    walkFiles: (rootPath) => walkFiles(rootPath, command),
+    readPackageJson: (rootPath) => readPackageJson(rootPath, command),
+    runGit: (rootPath, args) => runGit(rootPath, args, command),
+    detectTool: (name, rootPath) => detectTool(name, rootPath, command),
+  };
+}