@kontextmind/kxm 0.6.0 → 0.7.10

package/plugins/kxm/src/vnext-oneshot-evidence.ts

@@ -0,0 +1,117 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, open, rename } from "node:fs/promises";
+import { join } from "node:path";
+import type { VnextOneShotProcessResult } from "./vnext-oneshot-process.ts";
+
+export const ONESHOT_EVIDENCE_SCHEMA = "kxm.oneshot-evidence.v2" as const;
+const RETIRED_ONESHOT_EVIDENCE_SCHEMAS = new Set(["kxm.oneshot-evidence.v1"]);
+
+const TEXT_LIMIT = 4 * 1024 * 1024;
+const ARGV_LIMIT = 64 * 1024;
+const RECORD_LIMIT = 16 * 1024 * 1024;
+const digest = (value: string): string => `sha256:${createHash("sha256").update(value).digest("hex")}`;
+
+export interface OneShotEvidenceRecord {
+  schema: typeof ONESHOT_EVIDENCE_SCHEMA;
+  [key: string]: unknown;
+}
+
+/** Brake: retired and unknown persisted schema ids are never aliased or upgraded. */
+export function parseOneShotEvidenceRecord(bytes: string): OneShotEvidenceRecord {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(bytes) as unknown;
+  } catch {
+    throw new Error("oneshot_evidence_record_invalid");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("oneshot_evidence_record_invalid");
+  }
+  const schema = (parsed as { schema?: unknown }).schema;
+  if (typeof schema !== "string") throw new Error("oneshot_evidence_record_invalid");
+  if (RETIRED_ONESHOT_EVIDENCE_SCHEMAS.has(schema)) throw new Error("oneshot_evidence_schema_retired");
+  if (schema !== ONESHOT_EVIDENCE_SCHEMA) throw new Error("oneshot_evidence_schema_unknown");
+  return parsed as OneShotEvidenceRecord;
+}
+
+/** Private diagnostic evidence, never a peer reply or acceptance authority.
+ * Retained until operator archival; no automatic deletion of failed attempts.
+ * Each record is bounded; inability to reserve/write evidence fails closed.
+ */
+export async function beginOneShotEvidence(root: string, intent: {
+  runId: string; stepId: string; attemptId: string; assignmentId: string;
+  harness: string; provider: string; model: string; cwd: string;
+  command: string; args: readonly string[]; input?: string | undefined;
+}, sensitive: readonly string[]): Promise<{
+  id: string;
+  finish(result: VnextOneShotProcessResult, observation: unknown): Promise<string>;
+}> {
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  const stat = await lstat(root);
+  if (!stat.isDirectory() || stat.isSymbolicLink()
+    || (process.platform !== "win32" && ((stat.mode & 0o077) !== 0 || stat.uid !== process.getuid?.()))) {
+    throw new Error("oneshot_evidence_root_not_private");
+  }
+  const id = `evd_${randomUUID().replaceAll("-", "")}`;
+  const dir = join(root, id);
+  await mkdir(dir, { mode: 0o700 });
+  const secrets = [...new Set(sensitive.filter((value) => value.length >= 8))].sort((a, b) => b.length - a.length);
+  const redact = (value: string): string => {
+    let text = value;
+    for (const secret of secrets) text = text.replaceAll(secret, "[REDACTED]");
+    return text
+      .replace(/(\b(?:authorization|api[_-]?key|access[_-]?token|refresh[_-]?token|password|secret)\b["']?\s*[:=]\s*["']?)(?:Bearer\s+)?[^\s"',;}]+/gi, "$1[REDACTED]")
+      .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [REDACTED]");
+  };
+  const bounded = (value: string, max = TEXT_LIMIT): { text: string; truncated: boolean; sha256: string } => {
+    const bytes = Buffer.from(redact(value));
+    return { text: bytes.subarray(0, max).toString("utf8"), truncated: bytes.length > max, sha256: digest(redact(value)) };
+  };
+  const write = async (name: string, value: unknown): Promise<string> => {
+    const current = await lstat(dir);
+    if (!current.isDirectory() || current.isSymbolicLink()
+      || (process.platform !== "win32" && ((current.mode & 0o077) !== 0 || current.uid !== process.getuid?.()))) {
+      throw new Error("oneshot_evidence_directory_changed");
+    }
+    const bytes = JSON.stringify(value);
+    if (Buffer.byteLength(bytes) > RECORD_LIMIT) throw new Error("oneshot_evidence_record_limit");
+    parseOneShotEvidenceRecord(bytes);
+    const target = join(dir, name);
+    const partial = `${target}.partial`;
+    const file = await open(partial, "wx", 0o600);
+    try { await file.writeFile(bytes); await file.sync(); }
+    finally { await file.close(); }
+    await rename(partial, target);
+    if (process.platform !== "win32") {
+      const directory = await open(dir, "r");
+      try { await directory.sync(); } finally { await directory.close(); }
+    }
+    return digest(bytes);
+  };
+  await write("intent.json", {
+    schema: ONESHOT_EVIDENCE_SCHEMA, id, recordedAt: new Date().toISOString(),
+    runId: intent.runId, stepId: intent.stepId, attemptId: intent.attemptId, assignmentId: intent.assignmentId,
+    harness: intent.harness, provider: intent.provider, requestedModel: intent.model,
+    cwd: intent.cwd, command: redact(intent.command),
+    argv: bounded(JSON.stringify(intent.args), ARGV_LIMIT), stdin: intent.input === undefined ? null : bounded(intent.input),
+    env: null,
+    acceptance: false,
+  });
+  let finished = false;
+  return {
+    id,
+    async finish(result, observation) {
+      if (finished) throw new Error("oneshot_evidence_already_finished");
+      finished = true;
+      return write("result.json", {
+        schema: ONESHOT_EVIDENCE_SCHEMA, id, recordedAt: new Date().toISOString(),
+        stdout: bounded(result.stdout), stderr: bounded(result.stderr),
+        code: result.code, signal: result.signal ?? null, started: result.started ?? null,
+        observedChildExit: result.observedChildExit ?? null, terminationRequested: result.terminationRequested ?? null,
+        unverifiedDescendants: result.unverifiedDescendants ?? null,
+        error: result.error ? bounded(result.error.message) : null,
+        observation: bounded(JSON.stringify(observation)), acceptance: false,
+      });
+    },
+  };
+}

package/plugins/kxm/src/vnext-oneshot-process.ts

@@ -0,0 +1,187 @@
+import { spawn } from "node:child_process";
+
+export interface VnextOneShotProcessResult {
+  stdout: string;
+  stderr: string;
+  code: number | null;
+  signal?: NodeJS.Signals | null | undefined;
+  observedChildExit?: boolean | undefined;
+  started?: boolean | undefined;
+  /** Stop was requested; direct-child reaping cannot attest escaped descendants. */
+  terminationRequested?: boolean | undefined;
+  /**
+   * Direct-child close/reap is not descendant death. Unobserved process-group
+   * members stay unverified: never success, never a forged descendant failure.
+   */
+  unverifiedDescendants?: boolean | undefined;
+  error?: Error | undefined;
+}
+
+export interface VnextOneShotSpawnOptions {
+  cwd?: string | undefined;
+  env?: NodeJS.ProcessEnv | undefined;
+  input?: string | undefined;
+  timeoutMs?: number | undefined;
+  signal?: AbortSignal | undefined;
+  /** Only allowlisted Windows `.cmd` probes may set this; never a user string. */
+  shell?: boolean | undefined;
+}
+export type VnextOneShotSpawn = (command: string, args: readonly string[], options: VnextOneShotSpawnOptions) => Promise<VnextOneShotProcessResult>;
+
+const OUTPUT_LIMIT = 8 * 1024 * 1024;
+const KILL_GRACE_MS = 250;
+const DRAIN_GRACE_MS = 500;
+const REAP_GRACE_MS = 1000;
+
+/**
+ * POSIX process-group tree kill with fallback to direct child kill.
+ * Ensures orphaned subshells, test workers, and background daemons are pruned on cancellation/timeout.
+ */
+export function killProcessTree(child: ReturnType<typeof spawn>, signal: NodeJS.Signals = "SIGKILL"): void {
+  if (process.platform !== "win32" && child.pid) {
+    try {
+      process.kill(-child.pid, signal);
+      return;
+    } catch {
+      // Fall through to direct child kill if process group is unavailable
+    }
+  }
+  try {
+    child.kill(signal);
+  } catch {
+    // Direct kill error if child already exited
+  }
+}
+
+/** Bound both execution and pipe drain. Observing exit is not proof of descendant death. */
+export function defaultSpawn(command: string, args: readonly string[], options: VnextOneShotSpawnOptions): Promise<VnextOneShotProcessResult> {
+  if (options.signal?.aborted) {
+    return Promise.resolve({ stdout: "", stderr: "", code: null, started: false, observedChildExit: false, error: new Error("process_aborted") });
+  }
+  return new Promise((resolve) => {
+    const stdout: Buffer[] = [];
+    const stderr: Buffer[] = [];
+    let outputBytes = 0;
+    let outputChunks = 0;
+    let code: number | null = null;
+    let signal: NodeJS.Signals | null = null;
+    let observedChildExit = false;
+    let finished = false;
+    let stopping = false;
+    let closed = false;
+    let killSent = false;
+    let error: Error | undefined;
+    let wallTimer: ReturnType<typeof setTimeout> | undefined;
+    let killTimer: ReturnType<typeof setTimeout> | undefined;
+    let drainTimer: ReturnType<typeof setTimeout> | undefined;
+    let reapTimer: ReturnType<typeof setTimeout> | undefined;
+    let child: ReturnType<typeof spawn>;
+    const finish = (): void => {
+      if (finished) return;
+      // Direct-child close must not cancel SIGTERM → SIGKILL. Refuse to settle
+      // until the group kill has been sent, then reap on the existing timers.
+      if (stopping && !killSent) return;
+      finished = true;
+      for (const timer of [wallTimer, killTimer, drainTimer, reapTimer]) clearTimeout(timer);
+      options.signal?.removeEventListener("abort", onAbort);
+      child?.stdin?.destroy();
+      child?.stdout?.destroy();
+      child?.stderr?.destroy();
+      child?.unref();
+      const started = Boolean(child?.pid);
+      if (started && !observedChildExit) error ??= new Error("process_exit_unobserved");
+      const unverifiedDescendants = stopping || (started && !observedChildExit);
+      resolve({
+        stdout: Buffer.concat(stdout).toString("utf8"),
+        stderr: Buffer.concat(stderr).toString("utf8"),
+        code,
+        signal,
+        started,
+        observedChildExit,
+        terminationRequested: stopping,
+        ...(unverifiedDescendants ? { unverifiedDescendants: true } : {}),
+        ...(error ? { error } : {}),
+      });
+    };
+    const kill = (requested: NodeJS.Signals): void => {
+      killProcessTree(child, requested);
+    };
+    const stop = (reason: string): void => {
+      if (finished) return;
+      error ??= new Error(reason);
+      if (stopping) return;
+      stopping = true;
+      clearTimeout(wallTimer);
+      kill("SIGTERM");
+      killTimer = setTimeout(() => {
+        kill("SIGKILL");
+        killSent = true;
+        if (closed) { finish(); return; }
+        reapTimer = setTimeout(() => {
+          if (!observedChildExit) error ??= new Error("process_exit_unobserved");
+          finish();
+        }, REAP_GRACE_MS);
+      }, KILL_GRACE_MS);
+    };
+    const onAbort = (): void => stop("process_aborted");
+    try {
+      child = spawn(command, [...args], {
+        cwd: options.cwd,
+        env: options.env ?? process.env,
+        stdio: ["pipe", "pipe", "pipe"],
+        shell: options.shell === true,
+        windowsHide: true,
+        detached: process.platform !== "win32",
+      });
+    } catch (cause) {
+      error = cause instanceof Error ? cause : new Error("process_spawn_failed");
+      finish();
+      return;
+    }
+    const collect = (target: Buffer[], chunk: Buffer | string): void => {
+      if (finished) return;
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      const remaining = Math.max(0, OUTPUT_LIMIT - outputBytes);
+      if (remaining && outputChunks < 16384) {
+        const kept = bytes.subarray(0, remaining);
+        target.push(kept);
+        outputBytes += kept.length;
+        outputChunks++;
+      }
+      if (bytes.length > remaining || outputChunks >= 16384) stop("process_output_limit");
+    };
+    child.stdout!.on("data", (chunk: Buffer) => collect(stdout, chunk));
+    child.stderr!.on("data", (chunk: Buffer) => collect(stderr, chunk));
+    child.stdin!.on("error", () => stop("process_stdin_error"));
+    child.stdout!.on("error", () => stop("process_stdio_error"));
+    child.stderr!.on("error", () => stop("process_stdio_error"));
+    child.on("error", (cause) => {
+      error ??= cause;
+      if (!child.pid) finish();
+      else stop("process_error");
+    });
+    child.on("exit", (exitCode, exitSignal) => {
+      if (finished) return;
+      observedChildExit = true;
+      code = exitCode;
+      signal = exitSignal;
+      clearTimeout(wallTimer);
+      drainTimer = setTimeout(() => stop("process_stdio_unclosed"), DRAIN_GRACE_MS);
+    });
+    child.on("close", (exitCode, exitSignal) => {
+      if (finished) return;
+      closed = true;
+      code = exitCode;
+      signal = exitSignal;
+      // The leader can exit and close its pipes while a descendant ignores TERM.
+      // finish() no-ops until SIGKILL when escalation is in flight.
+      finish();
+    });
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    if (options.signal?.aborted) onAbort();
+    const timeoutMs = options.timeoutMs ?? 120_000;
+    if (!stopping) wallTimer = setTimeout(() => stop("process_timeout"), timeoutMs > 0 && Number.isFinite(timeoutMs) ? timeoutMs : 120_000);
+    try { child.stdin!.end(options.input); }
+    catch { stop("process_stdin_error"); }
+  });
+}