harnery 0.38.0 → 0.40.0

package/src/core/hooks/prompt-context/contract.ts

@@ -0,0 +1,177 @@
+import type { Adapter } from "../../adapter.ts";
+
+export const PROMPT_CONTEXT_REQUEST_SCHEMA = "harnery.prompt-context-request/v1" as const;
+export const PROMPT_CONTEXT_RESULT_SCHEMA = "harnery.prompt-context-result/v1" as const;
+
+export const DEFAULT_PROMPT_CONTEXT_TIMEOUT_MS = 15_000;
+export const DEFAULT_PROMPT_CONTEXT_MAX_OUTPUT_BYTES = 65_536;
+export const MAX_PROMPT_CONTEXT_TIMEOUT_MS = 120_000;
+export const MAX_PROMPT_CONTEXT_OUTPUT_BYTES = 4 * 1024 * 1024;
+
+const MAX_PROVIDER_ID_CHARS = 100;
+const MAX_REASON_CODES = 32;
+const MAX_REASON_CODE_CHARS = 80;
+
+export type PromptContextDelivery = "direct" | "unsupported";
+
+export interface PromptContextConfig {
+  enabled: boolean;
+  timeoutMs: number;
+  maxOutputBytes: number;
+}
+
+export interface PromptContextRequestV1 {
+  schema: typeof PROMPT_CONTEXT_REQUEST_SCHEMA;
+  event: "user_prompt_submit";
+  adapter: Adapter;
+  session_id: string;
+  turn_id: string;
+  cwd: string;
+  prompt: string;
+}
+
+export interface PromptContextResultV1 {
+  schema: typeof PROMPT_CONTEXT_RESULT_SCHEMA;
+  provider_id: string;
+  context: string;
+  matched: number;
+  succeeded: number;
+  failed: number;
+  reason_codes: string[];
+}
+
+export interface PromptContextAuditV1 {
+  provider_id?: string;
+  status:
+    | "disabled"
+    | "no_prompt"
+    | "missing_extension"
+    | "timeout"
+    | "signal"
+    | "nonzero_exit"
+    | "invalid_result"
+    | "oversized_result"
+    | "empty"
+    | "delivered";
+  delivery: PromptContextDelivery;
+  elapsed_ms: number;
+  matched?: number;
+  succeeded?: number;
+  failed?: number;
+  reason_codes?: string[];
+  output_bytes?: number;
+  context_fingerprint?: string;
+}
+
+export type PromptContextResultValidation =
+  | { ok: true; value: PromptContextResultV1 }
+  | { ok: false; reason: string };
+
+const DELIVERY_BY_ADAPTER: Readonly<Record<Adapter, PromptContextDelivery>> = {
+  "claude-code": "direct",
+  codex: "direct",
+  cursor: "direct",
+};
+
+export function promptContextDelivery(adapter: Adapter): PromptContextDelivery {
+  return DELIVERY_BY_ADAPTER[adapter] ?? "unsupported";
+}
+
+export function parsePromptContextConfig(value: unknown): PromptContextConfig | null {
+  if (value === undefined) {
+    return {
+      enabled: false,
+      timeoutMs: DEFAULT_PROMPT_CONTEXT_TIMEOUT_MS,
+      maxOutputBytes: DEFAULT_PROMPT_CONTEXT_MAX_OUTPUT_BYTES,
+    };
+  }
+  if (!isRecord(value) || typeof value.enabled !== "boolean") return null;
+
+  const timeoutMs = value.timeoutMs ?? DEFAULT_PROMPT_CONTEXT_TIMEOUT_MS;
+  const maxOutputBytes = value.maxOutputBytes ?? DEFAULT_PROMPT_CONTEXT_MAX_OUTPUT_BYTES;
+  if (!isBoundedInteger(timeoutMs, 1, MAX_PROMPT_CONTEXT_TIMEOUT_MS)) return null;
+  if (!isBoundedInteger(maxOutputBytes, 1, MAX_PROMPT_CONTEXT_OUTPUT_BYTES)) return null;
+
+  return { enabled: value.enabled, timeoutMs, maxOutputBytes };
+}
+
+export function buildPromptContextRequest(input: {
+  adapter: Adapter;
+  sessionId: string;
+  turnId: string;
+  cwd: string;
+  prompt: string;
+}): PromptContextRequestV1 {
+  return {
+    schema: PROMPT_CONTEXT_REQUEST_SCHEMA,
+    event: "user_prompt_submit",
+    adapter: input.adapter,
+    session_id: input.sessionId,
+    turn_id: input.turnId,
+    cwd: input.cwd,
+    prompt: input.prompt,
+  };
+}
+
+export function validatePromptContextResult(value: unknown): PromptContextResultValidation {
+  if (!isRecord(value)) return invalid("result_not_object");
+  if (value.schema !== PROMPT_CONTEXT_RESULT_SCHEMA) return invalid("unsupported_schema");
+  if (
+    typeof value.provider_id !== "string" ||
+    value.provider_id.length === 0 ||
+    value.provider_id.length > MAX_PROVIDER_ID_CHARS ||
+    !/^[a-z0-9][a-z0-9._-]*$/.test(value.provider_id)
+  ) {
+    return invalid("invalid_provider_id");
+  }
+  if (typeof value.context !== "string") return invalid("invalid_context");
+  if (!isCount(value.matched) || !isCount(value.succeeded) || !isCount(value.failed)) {
+    return invalid("invalid_counts");
+  }
+  if (value.succeeded + value.failed !== value.matched) return invalid("count_mismatch");
+  if (value.succeeded === 0 && value.context.length > 0) return invalid("context_without_success");
+  if (value.succeeded > 0 && value.context.length === 0) return invalid("success_without_context");
+  if (!Array.isArray(value.reason_codes) || value.reason_codes.length > MAX_REASON_CODES) {
+    return invalid("invalid_reason_codes");
+  }
+  if (
+    value.reason_codes.some(
+      (code) =>
+        typeof code !== "string" ||
+        code.length === 0 ||
+        code.length > MAX_REASON_CODE_CHARS ||
+        !/^[a-z0-9][a-z0-9._-]*$/.test(code),
+    )
+  ) {
+    return invalid("invalid_reason_code");
+  }
+
+  return {
+    ok: true,
+    value: {
+      schema: PROMPT_CONTEXT_RESULT_SCHEMA,
+      provider_id: value.provider_id,
+      context: value.context,
+      matched: value.matched,
+      succeeded: value.succeeded,
+      failed: value.failed,
+      reason_codes: [...value.reason_codes],
+    },
+  };
+}
+
+function invalid(reason: string): PromptContextResultValidation {
+  return { ok: false, reason };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isBoundedInteger(value: unknown, min: number, max: number): value is number {
+  return Number.isInteger(value) && (value as number) >= min && (value as number) <= max;
+}
+
+function isCount(value: unknown): value is number {
+  return Number.isSafeInteger(value) && (value as number) >= 0;
+}

package/src/core/hooks/prompt-context/index.ts

@@ -0,0 +1,22 @@
+export type {
+  PromptContextAuditV1,
+  PromptContextConfig,
+  PromptContextDelivery,
+  PromptContextRequestV1,
+  PromptContextResultV1,
+  PromptContextResultValidation,
+} from "./contract.ts";
+export {
+  buildPromptContextRequest,
+  DEFAULT_PROMPT_CONTEXT_MAX_OUTPUT_BYTES,
+  DEFAULT_PROMPT_CONTEXT_TIMEOUT_MS,
+  MAX_PROMPT_CONTEXT_OUTPUT_BYTES,
+  MAX_PROMPT_CONTEXT_TIMEOUT_MS,
+  PROMPT_CONTEXT_REQUEST_SCHEMA,
+  PROMPT_CONTEXT_RESULT_SCHEMA,
+  parsePromptContextConfig,
+  promptContextDelivery,
+  validatePromptContextResult,
+} from "./contract.ts";
+export type { PromptContextRunResult, RunPromptContextInput } from "./runner.ts";
+export { runPromptContext } from "./runner.ts";

package/src/core/hooks/prompt-context/runner.ts

@@ -0,0 +1,303 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import { createHmac } from "node:crypto";
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { Adapter } from "../../adapter.ts";
+import { hostPromptContextConfig } from "../../config.ts";
+import { loadOrCreateFingerprintKeyStoreV3 } from "../../events/v3/fingerprint-keys.ts";
+import { codexWslWorkspaceLinuxPath } from "../codex-wsl-bridge.ts";
+import {
+  buildPromptContextRequest,
+  type PromptContextAuditV1,
+  type PromptContextDelivery,
+  type PromptContextResultV1,
+  promptContextDelivery,
+  validatePromptContextResult,
+} from "./contract.ts";
+
+const EXTENSION_RELATIVE_PATH = [
+  "scripts",
+  "hooks",
+  "harness",
+  "extensions",
+  "prompt-context",
+] as const;
+
+const PROVIDER_ENV_ALLOWLIST = [
+  "COLORTERM",
+  "COMSPEC",
+  "HOME",
+  "LANG",
+  "LC_ALL",
+  "LC_CTYPE",
+  "LOGNAME",
+  "NO_COLOR",
+  "PATH",
+  "PATHEXT",
+  "SHELL",
+  "SYSTEMROOT",
+  "SystemRoot",
+  "TEMP",
+  "TERM",
+  "TMP",
+  "TMPDIR",
+  "TZ",
+  "USER",
+  "USERPROFILE",
+  "WINDIR",
+  "XDG_CACHE_HOME",
+  "XDG_CONFIG_HOME",
+  "XDG_DATA_HOME",
+] as const;
+
+const RESULT_KEYS = [
+  "context",
+  "failed",
+  "matched",
+  "provider_id",
+  "reason_codes",
+  "schema",
+  "succeeded",
+] as const;
+
+export interface RunPromptContextInput {
+  coordRoot: string;
+  adapter: Adapter;
+  sessionId: string;
+  turnId: string;
+  cwd: string;
+  prompt: string;
+  /** Test and embedding seam. Production callers should omit this. */
+  sourceEnv?: NodeJS.ProcessEnv;
+}
+
+export interface PromptContextRunResult {
+  context: string | null;
+  delivery: PromptContextDelivery;
+  audit: PromptContextAuditV1;
+}
+
+interface ChildResult {
+  kind: "closed" | "error" | "oversized" | "timeout";
+  stdout?: Buffer;
+  code?: number | null;
+  signal?: NodeJS.Signals | null;
+}
+
+/**
+ * Run one project-owned prompt-context provider behind Harnery's normalized
+ * prompt hook. Every provider failure returns metadata instead of throwing so
+ * optional context can never make the user's turn unusable.
+ */
+export async function runPromptContext(
+  input: RunPromptContextInput,
+): Promise<PromptContextRunResult> {
+  const startedAt = Date.now();
+  const delivery = promptContextDelivery(input.adapter);
+  const finish = (
+    status: PromptContextAuditV1["status"],
+    fields: Omit<PromptContextAuditV1, "status" | "delivery" | "elapsed_ms"> = {},
+    context: string | null = null,
+  ): PromptContextRunResult => ({
+    context,
+    delivery,
+    audit: {
+      status,
+      delivery,
+      elapsed_ms: Math.max(0, Date.now() - startedAt),
+      ...fields,
+    },
+  });
+
+  try {
+    const coordRoot = realDirectory(input.coordRoot);
+    const config = hostPromptContextConfig(coordRoot);
+    if (!config?.enabled) return finish("disabled");
+    if (!input.prompt.trim()) return finish("no_prompt");
+
+    const executable = join(coordRoot, ...EXTENSION_RELATIVE_PATH);
+    if (!isRegularFile(executable)) return finish("missing_extension");
+
+    const reportedCwd =
+      input.adapter === "codex"
+        ? (codexWslWorkspaceLinuxPath(coordRoot, input.cwd) ?? input.cwd)
+        : input.cwd;
+    const cwd = realDirectory(reportedCwd);
+    const request = buildPromptContextRequest({
+      adapter: input.adapter,
+      sessionId: input.sessionId,
+      turnId: input.turnId,
+      cwd,
+      prompt: input.prompt,
+    });
+    const child = await runExtension({
+      executable,
+      cwd,
+      stdin: `${JSON.stringify(request)}\n`,
+      env: providerEnvironment(input.sourceEnv ?? process.env),
+      timeoutMs: config.timeoutMs,
+      maxOutputBytes: config.maxOutputBytes,
+    });
+
+    if (child.kind === "timeout") return finish("timeout");
+    if (child.kind === "oversized") return finish("oversized_result");
+    if (child.kind === "error") return finish("missing_extension");
+    if (child.signal) return finish("signal");
+    if (child.code !== 0) return finish("nonzero_exit");
+
+    const stdout = child.stdout ?? Buffer.alloc(0);
+    const outputBytes = stdout.byteLength;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(stdout.toString("utf8"));
+    } catch {
+      return finish("invalid_result", { output_bytes: outputBytes });
+    }
+    if (!hasExactResultKeys(parsed)) {
+      return finish("invalid_result", { output_bytes: outputBytes });
+    }
+    const validated = validatePromptContextResult(parsed);
+    if (!validated.ok) return finish("invalid_result", { output_bytes: outputBytes });
+
+    const auditFields = providerAudit(validated.value, outputBytes);
+    if (!validated.value.context) return finish("empty", auditFields);
+
+    const contextFingerprint = fingerprintContext(coordRoot, validated.value.context);
+    return finish(
+      "delivered",
+      { ...auditFields, context_fingerprint: contextFingerprint },
+      validated.value.context,
+    );
+  } catch {
+    return finish("invalid_result");
+  }
+}
+
+function providerAudit(
+  result: PromptContextResultV1,
+  outputBytes: number,
+): Omit<PromptContextAuditV1, "status" | "delivery" | "elapsed_ms"> {
+  return {
+    provider_id: result.provider_id,
+    matched: result.matched,
+    succeeded: result.succeeded,
+    failed: result.failed,
+    reason_codes: [...result.reason_codes],
+    output_bytes: outputBytes,
+  };
+}
+
+function fingerprintContext(coordRoot: string, context: string): string {
+  const store = loadOrCreateFingerprintKeyStoreV3(coordRoot);
+  const epoch = store.epochs.find((candidate) => candidate.epoch_id === store.active_epoch_id);
+  if (!epoch) throw new Error("active fingerprint key is unavailable");
+  const key = Buffer.from(epoch.key_base64url, "base64url");
+  const digest = createHmac("sha256", key)
+    .update("harnery:prompt-context:v1\0", "utf8")
+    .update(context.normalize("NFC"), "utf8")
+    .digest("hex");
+  return `hmac-sha256:${digest}`;
+}
+
+function providerEnvironment(source: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {};
+  for (const name of PROVIDER_ENV_ALLOWLIST) {
+    const value = source[name];
+    if (value !== undefined) env[name] = value;
+  }
+  return env;
+}
+
+function hasExactResultKeys(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const keys = Object.keys(value).sort();
+  return (
+    keys.length === RESULT_KEYS.length && keys.every((key, index) => key === RESULT_KEYS[index])
+  );
+}
+
+function realDirectory(path: string): string {
+  const real = realpathSync(resolve(path));
+  if (!statSync(real).isDirectory()) throw new Error("workspace is not a directory");
+  return real;
+}
+
+function isRegularFile(path: string): boolean {
+  if (!existsSync(path)) return false;
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function runExtension(options: {
+  executable: string;
+  cwd: string;
+  stdin: string;
+  env: NodeJS.ProcessEnv;
+  timeoutMs: number;
+  maxOutputBytes: number;
+}): Promise<ChildResult> {
+  return new Promise((resolveResult) => {
+    let settled = false;
+    let timedOut = false;
+    let oversized = false;
+    let stdoutBytes = 0;
+    const stdout: Buffer[] = [];
+
+    const finish = (result: ChildResult): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolveResult(result);
+    };
+    const child = spawn(options.executable, [], {
+      cwd: options.cwd,
+      detached: process.platform !== "win32",
+      env: options.env,
+      shell: false,
+      stdio: ["pipe", "pipe", "ignore"],
+      windowsHide: true,
+    });
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killExtension(child);
+    }, options.timeoutMs);
+
+    child.stdout.on("data", (chunk: Buffer | string) => {
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      stdoutBytes += bytes.byteLength;
+      if (stdoutBytes > options.maxOutputBytes) {
+        oversized = true;
+        killExtension(child);
+        return;
+      }
+      stdout.push(bytes);
+    });
+    child.stdin.on("error", () => {
+      // The process outcome below remains authoritative. Broken input is
+      // represented as a nonzero exit, signal, or invalid empty result.
+    });
+    child.on("error", () => finish({ kind: "error" }));
+    child.on("close", (code, signal) => {
+      if (timedOut) return finish({ kind: "timeout" });
+      if (oversized) return finish({ kind: "oversized" });
+      return finish({ kind: "closed", stdout: Buffer.concat(stdout), code, signal });
+    });
+    child.stdin.end(options.stdin);
+  });
+}
+
+function killExtension(child: ChildProcess): void {
+  if (process.platform !== "win32" && child.pid) {
+    try {
+      process.kill(-child.pid, "SIGKILL");
+      return;
+    } catch {
+      // The process may have exited between the output/timeout boundary and
+      // this signal. Fall through to the ordinary child handle.
+    }
+  }
+  child.kill("SIGKILL");
+}

package/src/core/qa-artifacts.ts

@@ -6,14 +6,16 @@
  * full control of that explicit destination.
  */
 
-import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 import type { HarneryProgramContext } from "../commander.ts";
 import { monorepoRoot } from "./agents/index.ts";
 import {
   ARTIFACT_MANIFEST,
   type ArtifactManifestV2,
+  artifactReviewGuidance,
   artifactsRoot,
+  autoCleanArtifacts,
   configuredArtifactRetentionDays,
   createArtifact,
   parseArtifactManifest,
@@ -21,6 +23,23 @@ import {
 
 export type QaArtifactKind = "qa-run" | "qa-record" | "review-pack";
 
+/** Recognize managed outputs even when a detached child receives an explicit path. */
+export function managedQaReviewGuidance(repoRoot: string, outParent: string): string | undefined {
+  const path = resolve(outParent);
+  if (dirname(path) !== artifactsRoot(repoRoot)) return undefined;
+  try {
+    if (
+      lstatSync(path).isSymbolicLink() ||
+      lstatSync(join(path, ARTIFACT_MANIFEST)).isSymbolicLink()
+    )
+      return undefined;
+    const manifest = readQaManifest(join(path, ARTIFACT_MANIFEST));
+    return manifest ? artifactReviewGuidance(repoRoot, manifest.artifact_id) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export function resolveQaRepoRoot(context?: HarneryProgramContext): string {
   return resolve(context?.repoRoot ?? monorepoRoot() ?? process.cwd());
 }
@@ -28,8 +47,15 @@ export function resolveQaRepoRoot(context?: HarneryProgramContext): string {
 export function createManagedQaOutParent(
   repoRoot: string,
   kind: QaArtifactKind,
-  opts: { retentionMinutes?: number } = {},
+  opts: { retentionMinutes?: number; onCleanupWarning?: (message: string) => void } = {},
 ): string {
+  try {
+    autoCleanArtifacts(repoRoot);
+  } catch (error) {
+    opts.onCleanupWarning?.(
+      `artifact cleanup skipped: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
   return createArtifact(repoRoot, {
     slug: kind,
     purpose:

package/src/core/resources/contract.ts

@@ -1,4 +1,4 @@
-export const RESOURCE_SNAPSHOT_SCHEMA_VERSION = 1;
+export const RESOURCE_SNAPSHOT_SCHEMA_VERSION = 2;
 export const RESOURCE_SERVICE_STATUS_SCHEMA_VERSION = 1;
 
 export type ResourceSupportState = "supported" | "partial" | "unsupported" | "error";
@@ -29,6 +29,7 @@ export interface ResourceProcessGroup {
 }
 
 export interface ResourceMachineSample {
+  cpu_available_parallelism?: number;
   cpu_percent: number | null;
   cpu_logical_count: number;
   load_average: [number, number, number] | null;
@@ -38,7 +39,7 @@ export interface ResourceMachineSample {
   memory_percent: number | null;
   swap_total_bytes: number | null;
   swap_used_bytes: number | null;
-  process_count: number;
+  process_count: number | null;
 }
 
 export interface ResourceSnapshot {
@@ -51,10 +52,16 @@ export interface ResourceSnapshot {
   namespace: "host" | "wsl" | "unknown";
   support: {
     state: ResourceSupportState;
-    sampler: "procfs" | "unsupported";
+    sampler: "procfs" | "darwin" | "win32" | "unsupported";
     reason?: string;
   };
   machine: ResourceMachineSample;
+  disks?: ResourceDiskSample[];
+  pressure?: ResourcePressureSample;
+  oom?: ResourceOomSample;
+  vmstat?: ResourceVmstatSample;
+  io?: ResourceIoSample;
+  host?: ResourceHostSample;
   groups: ResourceProcessGroup[];
   processes: ResourceProcessSample[];
   visible_process_count: number;
@@ -62,6 +69,72 @@ export interface ResourceSnapshot {
   unattributed_process_count: number;
 }
 
+export interface ResourceDiskSample {
+  path: string;
+  state: ResourceSupportState;
+  total_bytes: number | null;
+  available_bytes: number | null;
+  used_percent: number | null;
+  reason?: string;
+}
+
+export interface ResourcePressureWindow {
+  avg10: number;
+  avg60: number;
+  avg300: number;
+}
+
+export interface ResourcePressureSample {
+  state: ResourceSupportState;
+  /** The CPU, memory, and I/O fields contain the kernel's some-stall averages. */
+  cpu: ResourcePressureWindow | null;
+  memory: ResourcePressureWindow | null;
+  io: ResourcePressureWindow | null;
+  memory_full: ResourcePressureWindow | null;
+  io_full: ResourcePressureWindow | null;
+  reason?: string;
+}
+
+export interface ResourceOomSample {
+  state: ResourceSupportState;
+  total_kills: number | null;
+  kills_since_last_sample: number | null;
+  last_kill_age_ms: number | null;
+  reason?: string;
+}
+
+/**
+ * Kernel memory-reclaim activity as per-second rates, from one bounded
+ * `/proc/vmstat` read. Rates need two consecutive samples: the first sample
+ * after a start, an observer restart, or a counter reset reports
+ * `counters_reset` with null rates rather than inventing a baseline.
+ */
+export interface ResourceVmstatSample {
+  state: ResourceSupportState;
+  swap_in_bytes_per_second: number | null;
+  swap_out_bytes_per_second: number | null;
+  direct_reclaim_pages_per_second: number | null;
+  major_faults_per_second: number | null;
+  counters_reset: boolean;
+  reason?: string;
+}
+
+export interface ResourceIoSample {
+  state: ResourceSupportState;
+  read_bytes_per_second: number | null;
+  write_bytes_per_second: number | null;
+  reason?: string;
+}
+
+export interface ResourceHostSample {
+  platform: "win32";
+  sampled_at: string;
+  state: ResourceSupportState;
+  machine: ResourceMachineSample | null;
+  disks: ResourceDiskSample[];
+  reason?: string;
+}
+
 export interface ResourceServiceStatusRecord {
   schema_version: typeof RESOURCE_SERVICE_STATUS_SCHEMA_VERSION;
   pid: number;

package/src/core/resources/index.ts

@@ -2,4 +2,5 @@ export * from "./contract.ts";
 export * from "./sampler.ts";
 export * from "./service.ts";
 export * from "./service-status.ts";
+export * from "./status.ts";
 export * from "./storage.ts";