paseo-req-kit 0.0.0-stage → 1.8.0-beta.3

package/engine/src/runtime.ts

@@ -0,0 +1,155 @@
+// The narrow surface the pipeline needs from Paseo. The real implementation is
+// paseo-runtime.ts; tests swap in a fake through REQ_PIPELINE_FAKE_RUNTIME.
+
+export type AgentRole = "builder" | "reviewer";
+
+export interface PendingPermission {
+  id: string;
+  title: string;
+}
+
+export interface WaitOutcome {
+  /** Same values as the SDK's waitForFinish(). */
+  status: "idle" | "error" | "permission" | "timeout";
+  error: string | null;
+  lastMessage: string | null;
+  pendingPermissions: PendingPermission[];
+  /** Usage the agent reports (its latest snapshot), when the provider reports it. */
+  usage?: import("./usage.js").AgentUsage | null;
+}
+
+export interface StepAgent {
+  readonly id: string;
+  /** Waits for the current turn, at most timeoutMs. Returns early on permission requests. */
+  wait(timeoutMs: number): Promise<WaitOutcome>;
+  /** Starts a new turn in the same session. Call wait() afterwards. */
+  followUp(text: string): Promise<void>;
+  archive(): Promise<void>;
+}
+
+export interface StartAgentInput {
+  role: AgentRole;
+  title: string;
+  prompt: string;
+  cwd: string;
+  labels: Record<string, string>;
+  /** Attach the step agent under this chat agent (shows in its Subagents track). */
+  parentAgentId: string | null;
+  /** Agent settings to launch with (the role's, or a review panel member's), Paseo profiles resolved. */
+  profile?: import("./config.js").AgentProfile;
+  /** Place the agent in this Paseo workspace (a worktree created for the requirement); still a subagent of parentAgentId. */
+  workspaceId?: string | null;
+}
+
+/** Where Paseo-managed services live: the chat's workspace, or the requirement's own worktree. */
+export type ServiceTarget = { agentId: string } | { workspaceId: string };
+
+export interface WorktreeRequest {
+  /** Checkout to cut the worktree from (the chat's directory). */
+  sourceRepo: string;
+  /** Branch or commit the new branch starts from. */
+  baseRef: string;
+  branchName: string;
+  title: string;
+  /** The chat; Paseo shows the workspace as created from it. */
+  callerAgentId: string | null;
+}
+
+/** A paseo.json service the pipeline runs through Paseo (supervised, own port per worktree). */
+export interface ManagedService {
+  name: string;
+  /** Address to use: Paseo's proxy URL when there is one, otherwise http://127.0.0.1:<port>. */
+  url: string | null;
+  port: number | null;
+  running: boolean;
+  health: "healthy" | "unhealthy" | null;
+  exitCode: number | null;
+  /** Last lines of the service's terminal, when they could be read. */
+  output: string | null;
+}
+
+/** One subscription window of a provider (Paseo's provider usage), e.g. "5 小时" at 92%. */
+export interface ProviderQuota {
+  provider: string;
+  displayName: string;
+  window: string;
+  usedPct: number | null;
+  resetsAt: string | null;
+  tone: "default" | "ok" | "warning" | "danger" | null;
+}
+
+/** A recent thing an agent did, in plain words, e.g. "运行命令：npm test". */
+export interface ActivityItem {
+  at: string;
+  text: string;
+}
+
+export interface ScheduledMessage {
+  agentId: string;
+  name: string;
+  prompt: string;
+  /** One run at this time; or `cron` for a recurring one. */
+  at?: Date;
+  cron?: string;
+  /** Recurring schedules stop by themselves at this time. */
+  expiresAt?: Date;
+}
+
+export interface ScheduledAgent {
+  name: string;
+  prompt: string;
+  cron: string;
+  cwd: string;
+  profile: import("./config.js").AgentProfile;
+}
+
+export interface AgentRuntime {
+  /**
+   * Checks that the chat which launched the pipeline exists and works in `cwd`.
+   * Step agents are created under that chat, and Paseo gives a subagent its parent's
+   * working directory, so the two must match. Throws with a user-facing reason otherwise.
+   */
+  verifyOrigin(agentId: string, cwd: string): Promise<void>;
+  startAgent(input: StartAgentInput): Promise<StepAgent>;
+  /** Delivers a message into an existing agent's conversation without interrupting it. */
+  notifyAgent(agentId: string, text: string): Promise<void>;
+  /** Interrupts the agent's current turn and gives it `text` instead (used to stop a step). */
+  interruptAgent(agentId: string, text: string): Promise<void>;
+  /** The daemon's agent profiles (Paseo settings → Agent profiles); null when they cannot be read. */
+  listPaseoProfiles(): Promise<import("./paseo-profiles.js").PaseoProfile[] | null>;
+  /**
+   * Names of the service scripts (paseo.json) of the workspace the chat works in. Null when
+   * Paseo cannot run them for us: no chat, an older daemon, or no services configured.
+   */
+  listServices(target: ServiceTarget): Promise<string[] | null>;
+  /** (Re)starts the services so they run the current code, and waits until they are ready or failed. */
+  startServices(target: ServiceTarget, names: string[], readyTimeoutMs: number): Promise<ManagedService[]>;
+  stopServices(target: ServiceTarget, names: string[]): Promise<void>;
+  /** Creates a Paseo worktree workspace (paseo.json setup runs in the background). */
+  createWorktree(request: WorktreeRequest): Promise<{ workspaceId: string; directory: string }>;
+  /** Waits for the workspace's paseo.json setup; "none" when there is nothing to wait for or it cannot be read. */
+  waitForWorkspaceSetup(workspaceId: string, timeoutMs: number): Promise<{ status: "completed" | "failed" | "none" | "timeout"; error: string | null }>;
+  /** Subscription windows of the given providers; null when Paseo has no usage data. */
+  providerQuota(providers: string[]): Promise<ProviderQuota[] | null>;
+  /** The agent's latest actions, oldest first; null when they cannot be read. */
+  recentActivity(agentId: string, limit: number): Promise<ActivityItem[] | null>;
+  /** Which Paseo tools step agents get (Settings → Agents); null when unknown. */
+  capabilities(): Promise<{ paseoTools: boolean; browser: boolean } | null>;
+  /**
+   * Paseo schedule that sends `prompt` into an existing agent's conversation (the chat):
+   * once at `at`, or on `cron` (5 fields, local time zone). Returns the schedule ID, or
+   * null when this Paseo cannot schedule.
+   */
+  scheduleMessage(input: ScheduledMessage): Promise<string | null>;
+  /** Paseo schedule that starts a fresh agent on `cron` (e.g. to run a command weekly). */
+  scheduleNewAgent(input: ScheduledAgent): Promise<string | null>;
+  cancelSchedule(id: string): Promise<void>;
+  close(): Promise<void>;
+}
+
+export interface RuntimeFactoryInput {
+  config: import("./config.js").PipelineConfig;
+  log: (message: string) => void;
+}
+
+export type RuntimeFactory = (input: RuntimeFactoryInput) => Promise<AgentRuntime>;

package/engine/src/schedule-time.ts

@@ -0,0 +1,51 @@
+// Times for Paseo schedules: parsing what people type ("22:00", "明天 8:30", "+2h")
+// and turning a moment into a one-shot cron expression in the local time zone.
+
+export function localTimeZone(): string {
+  return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+}
+
+/** "M H D Mon *" for one moment (the schedule is limited to one run). */
+export function cronAt(at: Date): string {
+  return `${at.getMinutes()} ${at.getHours()} ${at.getDate()} ${at.getMonth() + 1} *`;
+}
+
+/** Every N minutes, as cron: minutes under an hour, otherwise whole hours. */
+export function cronEvery(minutes: number): string {
+  if (minutes < 60) return `*/${Math.max(5, Math.round(minutes))} * * * *`;
+  return `0 */${Math.min(23, Math.max(1, Math.round(minutes / 60)))} * * *`;
+}
+
+/**
+ * Accepts "22:00" (today, or tomorrow when already past), "明天 8:30" / "tomorrow 8:30",
+ * "2026-10-14 08:30", "+90m", "+2h". Returns null when it cannot be read.
+ */
+export function parseStartTime(text: string, now = new Date()): Date | null {
+  const t = text.trim();
+  const rel = /^\+\s*(\d+(?:\.\d+)?)\s*(m|min|分钟|h|小时)$/i.exec(t);
+  if (rel) {
+    const n = Number(rel[1]);
+    const minutes = /^(m|min|分钟)$/i.test(rel[2]) ? n : n * 60;
+    return new Date(now.getTime() + Math.round(minutes * 60_000));
+  }
+  const full = /^(\d{4})-(\d{1,2})-(\d{1,2})[ T](\d{1,2}):(\d{2})$/.exec(t);
+  if (full) {
+    const d = new Date(Number(full[1]), Number(full[2]) - 1, Number(full[3]), Number(full[4]), Number(full[5]));
+    return Number.isNaN(d.getTime()) ? null : d;
+  }
+  const clock = /^(今天|明天|today|tomorrow)?\s*(\d{1,2})[:：](\d{2})$/i.exec(t);
+  if (clock) {
+    const h = Number(clock[2]);
+    const m = Number(clock[3]);
+    if (h > 23 || m > 59) return null;
+    const d = new Date(now.getFullYear(), now.getMonth(), now.getDate(), h, m);
+    const tomorrow = /^(明天|tomorrow)$/i.test(clock[1] ?? "");
+    if (tomorrow || (!clock[1] && d.getTime() <= now.getTime())) d.setDate(d.getDate() + 1);
+    return d;
+  }
+  return null;
+}
+
+export function describeTime(at: Date): string {
+  return at.toLocaleString("zh-CN", { hour12: false, month: "numeric", day: "numeric", hour: "2-digit", minute: "2-digit" });
+}

package/engine/src/smoke-test.ts

@@ -0,0 +1,202 @@
+// Checks the parts of the pipeline that depend on your real Paseo setup.
+//
+//   npm run smoke -- check                        daemon, providers, models, modes; one tiny agent per role
+//   npm run smoke -- notify --origin-agent <id>   message + subagent into an existing chat
+//   npm run smoke -- detach-start                 start a background heartbeat (run from a Paseo chat)
+//   npm run smoke -- detach-check                 is that heartbeat still alive?
+//
+// See docs/guide/安装与升级.md, "冒烟测试", for when to run each one.
+
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { type AgentProfile, loadConfig, type PipelineConfig } from "./config.js";
+import { checkProfile as checkProfileWith, type Client, connect, type Report, resolveWithDaemon } from "./daemon-check.js";
+import { defaultConfigPath } from "./locations.js";
+
+const HEARTBEAT = path.join(os.tmpdir(), "requirement-pipeline-heartbeat.json");
+
+function line(ok: boolean, text: string): void {
+  console.log(`${ok ? "✓" : "✗"} ${text}`);
+}
+
+const report: Report = (level, text, fix) => {
+  line(level !== "fail", text);
+  if (fix) console.log(`  ${fix}`);
+};
+
+async function tinyAgent(client: Client, role: string, profile: AgentProfile): Promise<boolean> {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), `requirement-pipeline-smoke-${role}-`));
+  const agent = await client.agents.create({
+    config: {
+      provider: profile.provider ?? "",
+      ...(profile.modeId ? { modeId: profile.modeId } : {}),
+      ...(profile.thinkingOptionId ? { thinkingOptionId: profile.thinkingOptionId } : {}),
+      ...(profile.featureValues ? { featureValues: profile.featureValues } : {}),
+    },
+    cwd: dir,
+    title: `[冒烟测试] ${role}`,
+    labels: { "requirement-pipeline": "smoke-test" },
+    prompt: `在当前目录创建文件 smoke.txt，内容只有一行：ok-${role}。然后用 node 执行 \`node -e "require('fs').writeFileSync('shell.txt','ran')"\`。完成后直接结束，不要做其他事。`,
+  });
+  console.log(`  已创建 agent ${agent.id}，等待它完成（最多 5 分钟）……`);
+  try {
+    const result = await agent.waitForFinish(5 * 60_000);
+    if (result.status === "permission") {
+      line(false, `${role}：agent 停下来等待权限批准。请把 agents.${role}.modeId 改成免确认的模式。`);
+      return false;
+    }
+    if (result.status !== "idle") {
+      line(false, `${role}：agent 结束状态为 ${result.status}：${result.error ?? ""}`);
+      return false;
+    }
+    const wrote = fs.existsSync(path.join(dir, "smoke.txt"));
+    const ran = fs.existsSync(path.join(dir, "shell.txt"));
+    line(wrote && ran, `${role}：agent 能写文件${wrote ? "" : "（失败）"}、能执行命令${ran ? "" : "（失败）"}`);
+    return wrote && ran;
+  } finally {
+    await agent.archive().catch(() => undefined);
+  }
+}
+
+async function check(config: PipelineConfig): Promise<number> {
+  let client: Client;
+  try {
+    client = await connect(config);
+    line(true, `已连接 daemon：${config.daemonUrl}`);
+  } catch (error) {
+    line(false, `无法连接 daemon ${config.daemonUrl}：${(error as Error).message}`);
+    return 1;
+  }
+  try {
+    const snapshot = await client.providers.waitForReady({ timeoutMs: 60_000 });
+    console.log("  daemon 上可用的 provider：");
+    for (const entry of snapshot.entries) {
+      console.log(`    - ${entry.provider}（${entry.status}）`);
+    }
+    try {
+      config = await resolveWithDaemon(client, config);
+    } catch (error) {
+      line(false, (error as Error).message);
+      return 1;
+    }
+    let ok = true;
+    for (const role of ["builder", "reviewer"] as const) {
+      ok = (await checkProfileWith(client, role, config.agents[role], report)) && ok;
+    }
+    if (!ok) {
+      console.log("\n请先修正 ~/.req-kit/config.json 中的 provider/model 和 modeId，再重新运行。");
+      return 1;
+    }
+    for (const role of ["builder", "reviewer"] as const) {
+      ok = (await tinyAgent(client, role, config.agents[role])) && ok;
+    }
+    console.log(ok ? "\n全部通过。" : "\n有检查没有通过，见上面的 ✗。");
+    return ok ? 0 : 1;
+  } finally {
+    await client.close();
+  }
+}
+
+async function notify(config: PipelineConfig, origin: string): Promise<number> {
+  const client = await connect(config);
+  try {
+    await client.agents.ref(origin).send(
+      "【需求开发流水线通知】这是一条冒烟测试消息，不是用户发的。请回复用户：\"流水线的通知通道工作正常。\"",
+      { activeTurnBehavior: "steer" },
+    );
+    line(true, `已向 agent ${origin} 发送测试通知。请到该对话中确认 agent 转告了"通知通道工作正常"。`);
+
+    config = await resolveWithDaemon(client, config);
+    const child = await client.agents.create({
+      config: {
+        provider: config.agents.builder.provider ?? "",
+        ...(config.agents.builder.modeId ? { modeId: config.agents.builder.modeId } : {}),
+      },
+      cwd: process.cwd(),
+      parent: origin,
+      title: "[冒烟测试] 子 agent",
+      labels: { "requirement-pipeline": "smoke-test" },
+      prompt: "只回复\"ok\"，然后结束。不要读写任何文件。",
+    });
+    const result = await child.waitForFinish(3 * 60_000);
+    line(result.status === "idle", `已在该对话下创建子 agent ${child.id}（结束状态 ${result.status}）。请确认它出现在对话的子 agent 列表中。`);
+    await child.archive().catch(() => undefined);
+    return result.status === "idle" ? 0 : 1;
+  } catch (error) {
+    line(false, (error as Error).message);
+    return 1;
+  } finally {
+    await client.close();
+  }
+}
+
+function detachStart(): number {
+  const script = `
+    const fs = require("fs");
+    const end = Date.now() + 10 * 60_000;
+    const beat = () => fs.writeFileSync(${JSON.stringify(HEARTBEAT)}, JSON.stringify({ pid: process.pid, at: Date.now(), startedAt }));
+    const startedAt = Date.now();
+    beat();
+    const timer = setInterval(() => { if (Date.now() > end) { clearInterval(timer); return; } beat(); }, 2000);
+  `;
+  // Same detach mechanism as launch.ts.
+  const child = spawn(process.execPath, ["-e", script], { detached: true, windowsHide: true, stdio: "ignore" });
+  child.unref();
+  console.log(`已启动后台心跳进程 ${child.pid}（持续 10 分钟），心跳文件：${HEARTBEAT}`);
+  console.log("请结束这一轮对话，等待至少 1 分钟后，再让 agent 运行 detach-check。");
+  return 0;
+}
+
+function detachCheck(): number {
+  if (!fs.existsSync(HEARTBEAT)) {
+    line(false, "找不到心跳文件，请先运行 detach-start");
+    return 1;
+  }
+  const beat = JSON.parse(fs.readFileSync(HEARTBEAT, "utf8")) as { pid: number; at: number; startedAt: number };
+  const age = Math.round((Date.now() - beat.at) / 1000);
+  const ranFor = Math.round((beat.at - beat.startedAt) / 1000);
+  const alive = age < 10;
+  line(
+    alive,
+    alive
+      ? `后台进程 ${beat.pid} 仍在运行（已运行 ${ranFor} 秒）。聊天 agent 启动的后台流水线可以在它的回合结束后继续运行。`
+      : `后台进程 ${beat.pid} 在启动后约 ${ranFor} 秒停止（最后一次心跳在 ${age} 秒前）。` +
+          "聊天 agent 的回合结束时，它启动的后台进程被终止了；需要改用插件方式启动流水线。",
+  );
+  return alive ? 0 : 1;
+}
+
+async function main(): Promise<number> {
+  const { values, positionals } = parseArgs({
+    args: process.argv.slice(2),
+    options: { "origin-agent": { type: "string" }, config: { type: "string" } },
+    allowPositionals: true,
+  });
+  const command = positionals[0];
+  if (command === "detach-start") return detachStart();
+  if (command === "detach-check") return detachCheck();
+
+  const config = loadConfig(values.config ? path.resolve(values.config) : defaultConfigPath()).config;
+  if (command === "check") return check(config);
+  if (command === "notify") {
+    const origin = values["origin-agent"] ?? process.env.PASEO_AGENT_ID;
+    if (!origin) {
+      console.error("需要 --origin-agent <agent ID>，或在 Paseo 的聊天中运行（自动读取 PASEO_AGENT_ID）");
+      return 2;
+    }
+    return notify(config, origin);
+  }
+  console.error("用法：npm run smoke -- check | notify --origin-agent <id> | detach-start | detach-check");
+  return 2;
+}
+
+main().then(
+  (code) => process.exit(code),
+  (error: Error) => {
+    console.error(error.message);
+    process.exit(1);
+  },
+);

package/engine/src/spec-review.ts

@@ -0,0 +1,100 @@
+// Independent review of a draft spec, started from the chat before the requester
+// confirms it (launch.ts --spec-review). Runs one "spec_review" agent under the chat,
+// waits for it in the background, then posts the findings back into the chat.
+
+import fs from "node:fs";
+import path from "node:path";
+import { parseLaunchArgs } from "./cli-args.js";
+import { loadConfig } from "./config.js";
+import { defaultConfigPath, KIT_ROOT, localPromptsDir, PRINCIPLES_INDEX, PROMPTS_DIR } from "./locations.js";
+import { specReviewFailedMessage, specReviewMessage } from "./messages.js";
+import { resolveConfigProfiles, usesPaseoProfiles } from "./paseo-profiles.js";
+import { runSingleStep } from "./pipeline.js";
+import { normalizeFeatureDir, specProfile } from "./preflight.js";
+import { loadRuntimeFactory } from "./runtime-loader.js";
+import { ensurePipelineDir, hashFile, type PipelineState, pipelineDir, STATE_VERSION } from "./state.js";
+
+function log(message: string): void {
+  console.log(`[${new Date().toISOString()}] ${message}`);
+}
+
+async function main(): Promise<number> {
+  const args = parseLaunchArgs(process.argv.slice(2));
+  const repo = fs.realpathSync(args.repo);
+  const featureDir = normalizeFeatureDir(repo, args.featureDir);
+  const specPath = path.join(repo, featureDir, "spec.md");
+  let config = loadConfig(args.configPath ?? defaultConfigPath(), repo).config;
+  ensurePipelineDir(repo, featureDir);
+  const runtime = await (await loadRuntimeFactory())({ config, log });
+  const origin = args.originAgentId;
+  const notify = async (text: string) => {
+    log(`通知：\n${text}`);
+    if (origin) await runtime.notifyAgent(origin, text).catch((error: Error) => log(`通知发送失败：${error.message}`));
+  };
+  try {
+    if (origin) await runtime.verifyOrigin(origin, repo);
+    if (usesPaseoProfiles(config)) config = resolveConfigProfiles(config, await runtime.listPaseoProfiles());
+    const now = new Date().toISOString();
+    // A scratch state: the review is not part of a pipeline run and must not touch state.json.
+    const state: PipelineState = {
+      version: STATE_VERSION,
+      repo,
+      featureDir,
+      status: "running",
+      attempt: 1,
+      specHash: hashFile(specPath),
+      originAgentId: origin,
+      pid: process.pid,
+      startedAt: now,
+      updatedAt: now,
+      results: {},
+      history: [],
+      stopReason: null,
+      outcome: null,
+      profile: specProfile(fs.readFileSync(specPath, "utf8")) ?? config.defaultProfile,
+      branch: null,
+      milestones: [],
+      incremental: null,
+    };
+    const result = await runSingleStep(
+      {
+        repo,
+        featureDir,
+        config,
+        runtime,
+        state,
+        statePath: path.join(pipelineDir(repo, featureDir), "spec-review-state.json"),
+        prompts: { promptsDir: PROMPTS_DIR, localPromptsDir: localPromptsDir(), principlesFile: PRINCIPLES_INDEX },
+        logPath: path.join(pipelineDir(repo, featureDir), "spec-review.log"),
+        resumeCommand: "",
+        log,
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+      },
+      "spec_review",
+      { contextLines: [`需求说明的写法清单：${path.join(KIT_ROOT, "skills", "spec-writing", "SKILL.md")}`] },
+    );
+    await notify(
+      specReviewMessage({
+        featureDir,
+        verdict: String(result.verdict),
+        issues: (result.issues as string[] | undefined) ?? [],
+        reviewPath: `${featureDir}/spec-review.md`,
+      }),
+    );
+    return 0;
+  } catch (error) {
+    log(`审阅没有完成：${(error as Error).message}`);
+    await notify(specReviewFailedMessage({ featureDir, reason: (error as Error).message }));
+    return 1;
+  } finally {
+    await runtime.close().catch(() => undefined);
+  }
+}
+
+main().then(
+  (code) => process.exit(code),
+  (error: Error) => {
+    console.error(`[${new Date().toISOString()}] 需求说明审阅无法启动：${error.message}`);
+    process.exit(2);
+  },
+);