paseo-req-kit 1.8.0 → 1.9.0-beta.1

package/engine/src/eval.ts

@@ -104,6 +104,8 @@ function runPipeline(repo: string, featureDir: string, c: EvalCase, configPath:
   const env = { ...process.env };
   delete env.PASEO_AGENT_ID;
   delete env.PASEO_AGENT_CWD;
+  // Evaluation runs are not real requirements: keep them out of the machine's index and usage records.
+  env.REQ_KIT_NO_RECORD = "1";
   const run = spawnSync(process.execPath, args, { cwd: repo, env, encoding: "utf8", timeout: timeoutMs, windowsHide: true });
   fs.appendFileSync(path.join(repo, featureDir, ".pipeline", "eval-run.log"), `${run.stdout ?? ""}${run.stderr ?? ""}`);
   if (run.error) return `流水线进程出错：${run.error.message}`;

package/engine/src/index-cmd.ts

@@ -0,0 +1,33 @@
+// `req index`: the machine's list of requirements (records.ts), for people.
+//   req index                      what is recorded
+//   req index --rebuild [<dir>...] record the requirements that have run in these repositories
+//                                  (default: here) and in those already recorded
+//   req index --prune              forget the requirements whose directory is gone
+
+import path from "node:path";
+import { apiIndex } from "./api.js";
+import { indexDir, readIndex } from "./records.js";
+
+const argv = process.argv.slice(2);
+const prune = argv.includes("--prune");
+const rebuildAt = argv.indexOf("--rebuild");
+const dirs = rebuildAt < 0 ? [] : argv.slice(rebuildAt + 1).filter((a) => !a.startsWith("--"));
+if (rebuildAt >= 0 && dirs.length === 0) dirs.push(process.cwd());
+
+if (rebuildAt >= 0 || prune) {
+  const r = apiIndex({ rebuild: dirs, prune });
+  if (rebuildAt >= 0) console.log(`扫描了 ${r.scanned.length} 个仓库，登记 ${r.registered} 个运行过的需求。`);
+  if (prune) console.log(`移除了 ${r.pruned} 个目录已不在的需求。`);
+  console.log(`本机共记录 ${r.total} 个需求（${indexDir()}）。`);
+} else {
+  const entries = readIndex();
+  if (entries.length === 0) {
+    console.log("本机还没有记录任何需求。1.9 之前运行过的需求：在项目目录运行 req index --rebuild。");
+  } else {
+    console.log(`本机记录的需求（${entries.length} 个；查看进度用 req api list --all 或 Paseo 插件）：`);
+    for (const e of entries) {
+      console.log(`- ${e.project}：${path.basename(e.featureDir)}${e.present ? "" : "（目录已不在，req index --prune 可以移除）"}`);
+      console.log(`  ${path.join(e.repo, e.featureDir)}`);
+    }
+  }
+}

package/engine/src/main.ts

@@ -2,6 +2,7 @@
 // from the chat agent's shell; can also be run in the foreground for debugging.
 
 import { execFileSync } from "node:child_process";
+import fs from "node:fs";
 import path from "node:path";
 import { approveCommand, LAUNCHER, parseLaunchArgs, resumeCommand, statusCommand, verifyCommand } from "./cli-args.js";
 import { dequeuedMessage, queuedMessage, watchdogPrompt } from "./messages.js";
@@ -13,6 +14,7 @@ import { satisfies } from "./daemon-check.js";
 import { describeAgentProfile, resolveConfigProfiles, usesPaseoProfiles } from "./paseo-profiles.js";
 import { jointProblem } from "./joint.js";
 import { runPipeline } from "./pipeline.js";
+import { appendRun, runRecord } from "./records.js";
 import { preflight, verifyPhaseProblem } from "./preflight.js";
 import { loadRuntimeFactory } from "./runtime-loader.js";
 import {
@@ -243,6 +245,28 @@ async function main(): Promise<number> {
     writeState(stateFile, state);
   }
 
+  // This run's usage record (1.9): written once when the process ends, however it ends.
+  let recorded = false;
+  const recordRun = () => {
+    if (recorded) return;
+    recorded = true;
+    const title = (() => {
+      try {
+        return (/^#\s+(.+)$/m.exec(fs.readFileSync(checked.specPath, "utf8"))?.[1] ?? path.basename(featureDir)).trim();
+      } catch {
+        return path.basename(featureDir);
+      }
+    })();
+    appendRun(
+      runRecord({
+        state,
+        runStartedAt: now,
+        title,
+        agents: { builder: describeAgentProfile(config.agents.builder), reviewer: describeAgentProfile(config.agents.reviewer) },
+      }),
+    );
+  };
+
   let releaseSlot = () => {};
   const shutdown = (signal: string) => {
     log(`收到 ${signal}，流水线停止`);
@@ -250,6 +274,7 @@ async function main(): Promise<number> {
     state.stopReason = `流水线进程被 ${signal} 终止`;
     state.queuedSince = null;
     writeState(stateFile, state);
+    recordRun();
     releaseSlot();
     release();
     process.exit(1);
@@ -331,6 +356,7 @@ async function main(): Promise<number> {
       writeState(stateFile, state);
     }
     await runtime.close().catch(() => undefined);
+    recordRun();
     releaseSlot();
     release();
   }

package/engine/src/records.ts

@@ -0,0 +1,271 @@
+// Machine records under the kit home (1.9, ADR 0026): what this machine knows beyond one
+// repository. Neither is committed anywhere; both are local to the machine.
+//
+//   index/<key>.json      one file per requirement that has run here: where it lives, so
+//                         `req api list --all` and the Paseo plugin can find every requirement
+//                         on the machine. The overview itself is still read live (ADR 0010).
+//   usage/runs.jsonl      one line per pipeline run (a process from start to stop): steps,
+//                         time, usage, gate and review rounds. What `req stats` reports on.
+//
+// Recording never affects a run: every write is best effort. REQ_KIT_NO_RECORD=1 turns both
+// off (evaluation runs are not real requirements).
+
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { kitHome, kitVersion } from "./locations.js";
+import type { PipelineState } from "./state.js";
+
+export const RECORD_SCHEMA = 1;
+
+function recordingOff(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.REQ_KIT_NO_RECORD === "1" || env.REQ_KIT_NO_RECORD === "true";
+}
+
+function real(p: string): string {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Index
+
+export interface IndexEntry {
+  schema: 1;
+  /** Stable key of the requirement on this machine (also the file name). */
+  key: string;
+  /** Where the requirement is developed (its own worktree when it has one). */
+  repo: string;
+  featureDir: string;
+  /** The checkout the chat works in, when the requirement has its own worktree. */
+  sourceRepo: string | null;
+  workspaceId: string | null;
+  /** Name of the project: the source checkout's directory name. */
+  project: string;
+  registeredAt: string;
+}
+
+export function indexDir(env: NodeJS.ProcessEnv = process.env): string {
+  return path.join(kitHome(env), "index");
+}
+
+/** Key of a requirement: the checkout people work in plus the feature directory. */
+export function requirementKey(sourceOrRepo: string, featureDir: string): string {
+  return createHash("sha1").update(`${real(sourceOrRepo)}\0${featureDir.split(path.sep).join("/")}`).digest("hex").slice(0, 16);
+}
+
+/** Records where this requirement lives, if it is not recorded that way already. Never throws. */
+export function registerRequirement(state: Pick<PipelineState, "repo" | "featureDir" | "worktree">, env: NodeJS.ProcessEnv = process.env): void {
+  if (recordingOff(env)) return;
+  try {
+    const source = state.worktree?.sourceRepo ?? null;
+    const key = requirementKey(source ?? state.repo, state.featureDir);
+    const file = path.join(indexDir(env), `${key}.json`);
+    const existing = readEntry(file);
+    const entry: IndexEntry = {
+      schema: 1,
+      key,
+      repo: real(state.repo),
+      featureDir: state.featureDir.split(path.sep).join("/"),
+      sourceRepo: source ? real(source) : null,
+      workspaceId: state.worktree?.workspaceId ?? null,
+      project: path.basename(real(source ?? state.repo)),
+      registeredAt: existing?.registeredAt ?? new Date().toISOString(),
+    };
+    if (existing && JSON.stringify(existing) === JSON.stringify(entry)) return;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(entry, null, 2)}\n`);
+    fs.renameSync(tmp, file);
+  } catch {
+    // The index is a convenience; the run goes on without it.
+  }
+}
+
+function readEntry(file: string): IndexEntry | null {
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, "utf8")) as IndexEntry;
+    return raw && typeof raw.repo === "string" && typeof raw.featureDir === "string" ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Every recorded requirement, with whether its directory is still there. */
+export function readIndex(env: NodeJS.ProcessEnv = process.env): Array<IndexEntry & { present: boolean }> {
+  const dir = indexDir(env);
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((n) => n.endsWith(".json"))
+    .map((n) => readEntry(path.join(dir, n)))
+    .filter((e): e is IndexEntry => e !== null)
+    .map((e) => ({ ...e, present: fs.existsSync(path.join(e.repo, e.featureDir, ".pipeline", "state.json")) }));
+}
+
+/** Removes the entries whose requirement is gone. Returns how many. */
+export function pruneIndex(env: NodeJS.ProcessEnv = process.env): number {
+  let removed = 0;
+  for (const e of readIndex(env)) {
+    if (e.present) continue;
+    fs.rmSync(path.join(indexDir(env), `${e.key}.json`), { force: true });
+    removed++;
+  }
+  return removed;
+}
+
+// ---------------------------------------------------------------------------
+// Usage records
+
+export interface StepUsageRecord {
+  key: string;
+  stepId: string;
+  phase: string | null;
+  attempt: number;
+  round: number | null;
+  startedAt: string;
+  endedAt: string | null;
+  minutes: number;
+  outcome: string;
+  inputTokens: number | null;
+  outputTokens: number | null;
+  costUsd: number | null;
+}
+
+/** One pipeline run: a process from its start to its end (contracts/usage-record.md). */
+export interface RunRecord {
+  schema: 1;
+  kind: "run";
+  machine: string;
+  kitVersion: string;
+  requirement: {
+    key: string;
+    project: string;
+    name: string;
+    title: string;
+    type: string | null;
+    profile: string;
+  };
+  run: {
+    startedAt: string;
+    endedAt: string;
+    attempt: number;
+    phase: string | null;
+    phaseMode: string | null;
+    /** State at the end of the run: completed, phase_done, waiting_for_approval, failed… */
+    status: string;
+    /** The report's verdict when the run completed (completed, completed_with_issues, not_completed). */
+    outcome: string | null;
+    stopReason: string | null;
+  };
+  agents: { builder: string | null; reviewer: string | null };
+  steps: StepUsageRecord[];
+  gate: { runs: number; failed: number };
+}
+
+export function usageDir(env: NodeJS.ProcessEnv = process.env): string {
+  return path.join(kitHome(env), "usage");
+}
+
+export function runsFile(env: NodeJS.ProcessEnv = process.env): string {
+  return path.join(usageDir(env), "runs.jsonl");
+}
+
+function minutesBetween(from: string, to: string | null, now: Date): number {
+  const end = to ? new Date(to) : now;
+  return Math.max(0, Math.round(((end.getTime() - new Date(from).getTime()) / 60_000) * 10) / 10);
+}
+
+/** The record of the run that started at `runStartedAt`, from the state at its end. */
+export function runRecord(input: {
+  state: PipelineState;
+  runStartedAt: string;
+  title: string;
+  agents: { builder: string | null; reviewer: string | null };
+  now?: Date;
+  machine?: string;
+}): RunRecord {
+  const { state } = input;
+  const now = input.now ?? new Date();
+  const source = state.worktree?.sourceRepo ?? state.repo;
+  const since = new Date(input.runStartedAt).getTime();
+  const steps = state.history
+    .filter((h) => new Date(h.startedAt).getTime() >= since)
+    .map(
+      (h): StepUsageRecord => ({
+        key: h.key,
+        stepId: h.stepId,
+        phase: h.phase ?? null,
+        attempt: h.attempt,
+        round: h.round,
+        startedAt: h.startedAt,
+        endedAt: h.endedAt,
+        minutes: minutesBetween(h.startedAt, h.endedAt, now),
+        outcome: h.outcome,
+        inputTokens: h.usage?.inputTokens ?? null,
+        outputTokens: h.usage?.outputTokens ?? null,
+        costUsd: h.usage?.totalCostUsd ?? null,
+      }),
+    );
+  const gateRuns = [...(state.gate?.runs ?? []), ...(state.joint ?? []).flatMap((j) => j.gate?.runs ?? [])].filter(
+    (r) => new Date(r.at).getTime() >= since,
+  );
+  return {
+    schema: 1,
+    kind: "run",
+    machine: input.machine ?? os.hostname(),
+    kitVersion: kitVersion(),
+    requirement: {
+      key: requirementKey(source, state.featureDir),
+      project: path.basename(real(source)),
+      name: path.basename(state.featureDir),
+      title: input.title,
+      type: state.type ?? null,
+      profile: state.profile,
+    },
+    run: {
+      startedAt: input.runStartedAt,
+      endedAt: now.toISOString(),
+      attempt: state.attempt,
+      phase: state.phase ?? null,
+      phaseMode: state.phases?.mode ?? null,
+      status: state.status,
+      outcome: state.status === "completed" ? state.outcome : null,
+      stopReason: state.stopReason,
+    },
+    agents: input.agents,
+    steps,
+    gate: { runs: gateRuns.length, failed: gateRuns.filter((r) => !r.passed).length },
+  };
+}
+
+/** Appends a run record. Never throws. */
+export function appendRun(record: RunRecord, env: NodeJS.ProcessEnv = process.env): void {
+  if (recordingOff(env)) return;
+  try {
+    fs.mkdirSync(usageDir(env), { recursive: true });
+    fs.appendFileSync(runsFile(env), `${JSON.stringify(record)}\n`);
+  } catch {
+    // Usage records are a convenience; the run is not affected.
+  }
+}
+
+/** Run records from a JSONL file (this machine's, or an export from another). Bad lines are skipped. */
+export function readRuns(file: string): RunRecord[] {
+  if (!fs.existsSync(file)) return [];
+  const out: RunRecord[] = [];
+  for (const line of fs.readFileSync(file, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const r = JSON.parse(line) as RunRecord;
+      if (r && r.kind === "run" && r.schema === RECORD_SCHEMA && r.requirement && r.run) out.push(r);
+    } catch {
+      // A torn last line (power loss mid-write) or a foreign line.
+    }
+  }
+  return out;
+}

package/engine/src/state.ts

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import type { DefectHandling, PhaseMode, ProfileName, RequirementType, VerifyEnvironment } from "./config.js";
+import { registerRequirement } from "./records.js";
 import type { AgentUsage } from "./usage.js";
 import type { StepId } from "./steps.js";
 
@@ -246,6 +247,8 @@ export function writeState(file: string, state: PipelineState): void {
   const tmp = `${file}.${process.pid}.tmp`;
   fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
   fs.renameSync(tmp, file);
+  // The machine's index of requirements (1.9): written once, and again only if it moved.
+  registerRequirement(state);
 }
 
 export function hashFile(file: string): string {