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

package/engine/src/configure.ts

@@ -0,0 +1,237 @@
+// Configuration wizard: `node install.mjs --configure` (or `req configure`).
+// Lists what the local Paseo daemon offers and writes ~/.req-kit/config.json from
+// a few multiple-choice questions, so nobody has to hand-edit JSON or guess mode names.
+
+import fs from "node:fs";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+import { parseArgs } from "node:util";
+import type { AgentProfile } from "./config.js";
+import { connect } from "./daemon-check.js";
+import { type PaseoProfile, profilesFromDaemonConfig } from "./paseo-profiles.js";
+import { defaultConfigPath, KIT_ROOT } from "./locations.js";
+
+export interface CatalogEntry {
+  id: string;
+  label?: string;
+}
+
+/** What the daemon offers; the real one wraps the Paseo SDK, tests use a fixed one. */
+export interface Catalog {
+  providers(): Promise<Array<CatalogEntry & { status: string }>>;
+  models(provider: string): Promise<CatalogEntry[]>;
+  modes(provider: string): Promise<CatalogEntry[]>;
+  /** Agent profiles set up in Paseo; optional. */
+  profiles?(): Promise<PaseoProfile[]>;
+}
+
+export interface Choice<T> {
+  label: string;
+  value: T;
+}
+
+/** Asks one multiple-choice question; options[0] is the recommendation. */
+export type Chooser = <T>(question: string, options: Choice<T>[]) => Promise<T>;
+
+const ROLE_TEXT = {
+  builder: "builder（方案设计、写代码、修复、写报告）",
+  reviewer: "reviewer（方案审核、代码评审、功能验证）",
+} as const;
+
+/** Mode that never stops for approval, per provider; null when the provider has no modes. */
+export function unattendedMode(provider: string, modes: CatalogEntry[]): string | null {
+  if (modes.length === 0) return null;
+  const preferred: Record<string, string[]> = {
+    claude: ["bypassPermissions"],
+    codex: ["full-access"],
+    opencode: ["build"],
+  };
+  const ids = modes.map((m) => m.id);
+  for (const id of preferred[provider] ?? ["full-access", "bypassPermissions", "build"]) {
+    if (ids.includes(id)) return id;
+  }
+  return null;
+}
+
+/** Builds one role's agent settings from the chosen provider, model and mode. */
+export function profileFor(provider: string, model: string, modeId: string | null): AgentProfile {
+  const profile: AgentProfile = { provider: `${provider}/${model}` };
+  if (modeId) profile.modeId = modeId;
+  if (provider === "opencode") profile.featureValues = { auto_accept: true };
+  return profile;
+}
+
+const ROLE_HINTS = {
+  builder: /实现|开发|编码|写代码|implement|build|cod/i,
+  reviewer: /评审|审核|审查|检查|review|audit/i,
+} as const;
+
+/** Offers the Paseo profiles first, when there are any; null means "choose the agent directly". */
+async function chooseProfile(
+  role: "builder" | "reviewer",
+  profiles: PaseoProfile[],
+  choose: Chooser,
+  avoidProvider: string | null,
+): Promise<PaseoProfile | null> {
+  const usable = profiles.filter((p) => p.model);
+  if (usable.length === 0) return null;
+  const score = (p: PaseoProfile) =>
+    (ROLE_HINTS[role].test(`${p.name} ${p.notes ?? ""}`) ? 2 : 0) + (avoidProvider && p.provider !== avoidProvider ? 1 : 0);
+  const ordered = [...usable].sort((a, b) => score(b) - score(a));
+  const picked = await choose<PaseoProfile | null>(`${ROLE_TEXT[role]}用 Paseo 中的哪个 agent profile？`, [
+    ...ordered.map((p) => ({
+      label: `「${p.name}」：${p.provider}/${p.model}${p.modeId ? `，模式 ${p.modeId}` : ""}${p.notes ? `（${p.notes.slice(0, 40)}）` : ""}`,
+      value: p as PaseoProfile | null,
+    })),
+    { label: "不用 profile，直接选择 agent 和模型", value: null },
+  ]);
+  return picked;
+}
+
+async function chooseRole(
+  role: "builder" | "reviewer",
+  catalog: Catalog,
+  choose: Chooser,
+  avoidProvider: string | null,
+  profiles: PaseoProfile[] = [],
+): Promise<AgentProfile> {
+  const fromPaseo = await chooseProfile(role, profiles, choose, avoidProvider);
+  if (fromPaseo) return { paseoProfile: fromPaseo.name };
+  const providers = (await catalog.providers()).filter((p) => p.status === "ready");
+  if (providers.length === 0) throw new Error("daemon 上没有可用的 agent。请先在 Paseo 中安装并登录至少一种 agent。");
+  // Recommend a different provider for the reviewer: a second model catches different problems.
+  const ordered = avoidProvider ? [...providers.filter((p) => p.id !== avoidProvider), ...providers.filter((p) => p.id === avoidProvider)] : providers;
+  const provider = await choose(
+    `${ROLE_TEXT[role]}用哪个 agent？${avoidProvider ? "（建议与 builder 不同，评审更容易发现问题）" : ""}`,
+    ordered.map((p) => ({ label: p.label ? `${p.label}（${p.id}）` : p.id, value: p.id })),
+  );
+  const models = await catalog.models(provider);
+  if (models.length === 0) throw new Error(`${provider} 没有列出可用的模型。请在 Paseo 中检查它的登录状态。`);
+  const model = await choose(
+    `${ROLE_TEXT[role]}用哪个模型？`,
+    models.map((m) => ({ label: m.label && m.label !== m.id ? `${m.label}（${m.id}）` : m.id, value: m.id })),
+  );
+  const modes = await catalog.modes(provider);
+  let modeId = unattendedMode(provider, modes);
+  if (modes.length > 0 && !modeId) {
+    modeId = await choose(
+      `没有找到 ${provider} 的免确认模式，请选择一个不会停下来等待批准的模式：`,
+      modes.map((m) => ({ label: m.label ? `${m.label}（${m.id}）` : m.id, value: m.id })),
+    );
+  }
+  return profileFor(provider, model, modeId);
+}
+
+export interface WizardResult {
+  config: Record<string, unknown>;
+  summary: string[];
+}
+
+/** Asks the questions and returns the new config (existing settings are kept). */
+export async function runWizard(existing: Record<string, unknown>, catalog: Catalog, choose: Chooser): Promise<WizardResult> {
+  const profiles = (await catalog.profiles?.().catch(() => [])) ?? [];
+  const providerOf = (p: AgentProfile) => (p.provider ?? profiles.find((x) => x.name === p.paseoProfile)?.provider ?? "").split("/")[0];
+  const builder = await chooseRole("builder", catalog, choose, null, profiles);
+  const reviewer = await chooseRole("reviewer", catalog, choose, providerOf(builder), profiles);
+  const defaultProfile = await choose("没有特别说明时，需求默认走哪个档位？", [
+    { label: "标准：完整的方案审核、代码评审和验证（推荐）", value: "standard" },
+    { label: "快速：每个环节一轮，适合以小改动为主的项目", value: "quick" },
+  ]);
+  const notifyMilestones = await choose("开发过程中要不要在对话里发几句进展（方案定了、开始验证等）？", [
+    { label: "要（推荐）", value: true },
+    { label: "不要，只发需要处理的事和最终结果", value: false },
+  ]);
+  const config = { ...existing, agents: { builder, reviewer }, defaultProfile, notifyMilestones };
+  const describe = (p: AgentProfile) =>
+    p.paseoProfile
+      ? `Paseo profile「${p.paseoProfile}」（在 Paseo 中修改这个 profile 即可换模型）`
+      : `${p.provider}${p.modeId ? `（模式 ${p.modeId}）` : ""}${p.featureValues ? "，自动接受权限请求" : ""}`;
+  return {
+    config,
+    summary: [`builder：${describe(builder)}`, `reviewer：${describe(reviewer)}`, `默认档位：${defaultProfile}`, `进展通知：${notifyMilestones ? "开" : "关"}`],
+  };
+}
+
+function terminalChooser(): { choose: Chooser; close: () => void } {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const choose: Chooser = async (question, options) => {
+    console.log(`\n${question}`);
+    options.forEach((o, i) => console.log(`  ${i + 1}. ${o.label}${i === 0 ? "  ← 推荐" : ""}`));
+    for (;;) {
+      const answer = (await rl.question(`请输入编号（直接回车选 1）：`)).trim();
+      if (answer === "") return options[0].value;
+      const n = Number(answer);
+      if (Number.isInteger(n) && n >= 1 && n <= options.length) return options[n - 1].value;
+      console.log(`请输入 1 到 ${options.length} 之间的编号。`);
+    }
+  };
+  return { choose, close: () => rl.close() };
+}
+
+async function main(): Promise<number> {
+  const { values } = parseArgs({ args: process.argv.slice(2), options: { config: { type: "string" } } });
+  const configPath = values.config ? path.resolve(values.config) : defaultConfigPath();
+  const existing = fs.existsSync(configPath)
+    ? (JSON.parse(fs.readFileSync(configPath, "utf8")) as Record<string, unknown>)
+    : (JSON.parse(fs.readFileSync(path.join(KIT_ROOT, "config.example.json"), "utf8")) as Record<string, unknown>);
+  const settings = {
+    daemonUrl: typeof existing.daemonUrl === "string" ? existing.daemonUrl : "ws://127.0.0.1:6767/ws",
+    daemonPasswordEnv: typeof existing.daemonPasswordEnv === "string" ? existing.daemonPasswordEnv : "PASEO_DAEMON_PASSWORD",
+  };
+  console.log(`配置向导：连接 Paseo daemon ${settings.daemonUrl} ……`);
+  let client;
+  try {
+    client = await connect(settings as never);
+  } catch (error) {
+    console.error(`无法连接 daemon：${(error as Error).message}`);
+    console.error(`请确认 Paseo 正在运行；设置了密码时，确认环境变量 ${settings.daemonPasswordEnv} 已设置。`);
+    return 1;
+  }
+  const catalog: Catalog = {
+    async providers() {
+      const snapshot = await client.providers.waitForReady({ timeoutMs: 60_000 });
+      return snapshot.entries.map((e) => ({ id: e.provider, status: e.status }));
+    },
+    async models(provider) {
+      return ((await client.providers.listModels(provider)).models ?? []).map((m) => ({ id: m.id, label: m.label }));
+    },
+    async modes(provider) {
+      return ((await client.providers.listModes(provider)).modes ?? []).map((m) => ({ id: m.id, label: m.label }));
+    },
+    async profiles() {
+      return profilesFromDaemonConfig((await client.config.get()).config) ?? [];
+    },
+  };
+  const terminal = terminalChooser();
+  try {
+    const { config, summary } = await runWizard(existing, catalog, terminal.choose);
+    console.log("\n将写入以下设置：");
+    for (const line of summary) console.log(`  ${line}`);
+    const ok = await terminal.choose("确认写入吗？", [
+      { label: "写入", value: true },
+      { label: "放弃", value: false },
+    ]);
+    if (!ok) {
+      console.log("没有修改配置。");
+      return 1;
+    }
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    if (fs.existsSync(configPath)) fs.copyFileSync(configPath, `${configPath}.bak-${Date.now()}`);
+    fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+    console.log(`\n已写入 ${configPath}（原文件已备份）。接下来运行 npm run smoke -- check 确认两个 agent 能正常工作。`);
+    return 0;
+  } finally {
+    terminal.close();
+    await client.close().catch(() => undefined);
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(import.meta.filename)) {
+  main().then(
+    (code) => process.exit(code),
+    (error: Error) => {
+      console.error(`配置向导出错：${error.message}`);
+      process.exit(1);
+    },
+  );
+}

package/engine/src/control.ts

@@ -0,0 +1,230 @@
+// --status and --stop: what a chat agent runs when the user asks "how far along
+// is it?" or "stop for now". Output is plain language for relaying to the user.
+
+import { describeActivity } from "./activity.js";
+import { PHASE_MODE_LABELS, PROFILE_LABELS, type PipelineConfig } from "./config.js";
+import type { AgentRuntime, RuntimeFactory } from "./runtime.js";
+import { isAlive, type PipelineState, readState, type StepRecord, writeState } from "./state.js";
+import { STEPS } from "./steps.js";
+import { describeTotals, totals } from "./usage.js";
+
+export function duration(fromIso: string, to: Date = new Date()): string {
+  const minutes = Math.floor((to.getTime() - new Date(fromIso).getTime()) / 60_000);
+  if (minutes < 1) return "不到 1 分钟";
+  if (minutes < 60) return `${minutes} 分钟`;
+  const hours = Math.floor(minutes / 60);
+  const rest = minutes % 60;
+  return rest === 0 ? `${hours} 小时` : `${hours} 小时 ${rest} 分`;
+}
+
+const RESULT_TEXT: Record<string, string> = {
+  approved: "通过",
+  changes_required: "需要修改",
+  blocked: "需要需求方决定",
+  pass: "通过",
+  defects_found: "发现问题",
+  defects_remaining: "仍有问题",
+  done: "完成",
+  partial: "部分完成",
+  completed: "已完成，可以验收",
+  completed_with_issues: "已完成，有遗留问题",
+  not_completed: "未完成",
+};
+
+function resultText(record: StepRecord): string {
+  const r = record.result ?? {};
+  if (typeof r.has_runnable_service === "boolean") return r.has_runnable_service ? "完成（项目有常驻服务）" : "完成";
+  if (typeof r.started === "boolean") return r.started ? "服务启动成功" : "服务启动失败";
+  for (const key of ["verdict", "result", "status", "outcome"]) {
+    const value = r[key];
+    if (typeof value === "string") return RESULT_TEXT[value] ?? value;
+  }
+  return "完成";
+}
+
+function stepName(record: StepRecord): string {
+  const title = STEPS[record.stepId].title;
+  return record.round !== null ? `${title}（第 ${record.round} 轮）` : title;
+}
+
+export function describeStatus(state: PipelineState | null, featureDir: string, now = new Date()): string {
+  if (!state) return `需求 ${featureDir} 还没有启动过开发流水线。`;
+  const running = state.status === "running" && isAlive(state.pid);
+  const statusText = running
+    ? "运行中"
+    : state.status === "running"
+      ? "已中断（后台进程意外退出，可以继续）"
+      : state.status === "waiting_for_business"
+        ? "已暂停，等待需求方决定"
+        : state.status === "phase_done"
+          ? "研发完成，待测试验证（提测说明见功能目录中的 handoff.md）"
+        : state.status === "failed"
+          ? "已中断，可以继续"
+          : state.phases?.mode === "develop-only" && state.phase !== "verify"
+            ? `研发已完成，待人工测试（只做研发；研发结论：${RESULT_TEXT[state.outcome ?? ""] ?? state.outcome ?? ""}）`
+            : `已完成（${RESULT_TEXT[state.outcome ?? ""] ?? state.outcome ?? ""}）`;
+
+  const lines = [
+    `需求：${featureDir}（档位：${PROFILE_LABELS[state.profile ?? "standard"]}）`,
+    `状态：${running && state.queuedSince ? `排队中（本机同时运行的流水线已达上限，自 ${new Date(state.queuedSince).toLocaleString("zh-CN", { hour12: false })} 起等待，轮到时自动开始）` : statusText}`,
+    ...(state.phases && state.phases.mode !== "continuous"
+      ? [`执行方式：${PHASE_MODE_LABELS[state.phases.mode]}（当前阶段：${state.phase === "verify" ? "测试验证" : "研发"}${state.handbacks ? `，测试已退回 ${state.handbacks} 次` : ""}）`]
+      : []),
+    `开始时间：${new Date(state.startedAt).toLocaleString("zh-CN", { hour12: false })}，距今 ${duration(state.startedAt, now)}`,
+  ];
+  if (state.stopReason && !running) lines.push(`原因：${state.stopReason}`);
+  const KIND_TEXT = { reminder: "提醒", "auto-resume": "自动继续", watchdog: "定时检查", "verify-start": "开始测试验证" } as const;
+  for (const s of state.schedules ?? []) {
+    if (s.kind === "watchdog" && !running) continue;
+    const when = s.at ? `${new Date(s.at).toLocaleString("zh-CN", { hour12: false, month: "numeric", day: "numeric", hour: "2-digit", minute: "2-digit" })} ` : "";
+    lines.push(`已预约：${when}${KIND_TEXT[s.kind]}（Paseo 定时任务，执行暂停命令可以取消）`);
+  }
+
+  const records = state.history.filter((h) => h.attempt === state.attempt);
+  const current = records.find((h) => h.outcome === "running");
+  if (current && running) {
+    lines.push(`当前步骤：${stepName(current)}，已进行 ${duration(current.startedAt, now)}`);
+  }
+  const done = records.filter((h) => h.outcome === "completed");
+  if (done.length > 0) {
+    lines.push("已完成的步骤：");
+    done.forEach((h, i) => {
+      const took = h.endedAt ? duration(h.startedAt, new Date(h.endedAt)) : "";
+      lines.push(`  ${i + 1}. ${stepName(h)}：${resultText(h)}${took ? `（用时 ${took}）` : ""}`);
+    });
+  } else if (!current) {
+    lines.push("还没有完成的步骤。");
+  }
+  const failed = records.filter((h) => h.outcome === "failed").at(-1);
+  if (failed && !running) lines.push(`中断在：${stepName(failed)}（${failed.error ?? "原因未知"}）`);
+  if (records.length > 0) lines.push(`用时与用量：${describeTotals(totals(records, now))}`);
+  if (state.attempt > 1) lines.push(`这个需求的全部 ${state.attempt} 次尝试合计：${describeTotals(totals(state.history, now))}`);
+  if (state.phases && state.phases.mode !== "continuous") {
+    const verify = state.history.filter((h) => h.phase === "verify");
+    if (verify.length > 0) {
+      lines.push(`其中研发阶段：${describeTotals(totals(state.history.filter((h) => (h.phase ?? "develop") === "develop"), now))}；测试验证阶段：${describeTotals(totals(verify, now))}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+export interface StopInput {
+  statePath: string;
+  featureDir: string;
+  config: PipelineConfig;
+  createRuntime: RuntimeFactory;
+  log: (message: string) => void;
+  sleep: (ms: number) => Promise<void>;
+}
+
+/** Stops a running pipeline and its current step agent. Returns the message for the user. */
+/** Cancels the Paseo schedules a run left (reminder, automatic continuation, watchdog). */
+async function cancelSchedules(input: StopInput, state: PipelineState): Promise<number> {
+  const schedules = state.schedules ?? [];
+  if (schedules.length === 0) return 0;
+  try {
+    const runtime = await input.createRuntime({ config: input.config, log: input.log });
+    for (const s of schedules) await runtime.cancelSchedule(s.id).catch((error: Error) => input.log(`无法取消定时任务 ${s.id}：${error.message}`));
+    await runtime.close().catch(() => undefined);
+  } catch (error) {
+    input.log(`无法连接 Paseo 取消定时任务：${(error as Error).message}`);
+    return 0;
+  }
+  const latest = readState(input.statePath) ?? state;
+  latest.schedules = [];
+  writeState(input.statePath, latest);
+  return schedules.length;
+}
+
+export async function stopPipeline(input: StopInput): Promise<{ stopped: boolean; message: string }> {
+  const state = readState(input.statePath);
+  if (!state) return { stopped: false, message: `需求 ${input.featureDir} 还没有启动过开发流水线。` };
+  const cancelled = await cancelSchedules(input, state);
+  const cancelledText = cancelled > 0 ? `已取消预约的提醒或自动继续（${cancelled} 个）。` : "";
+  if (state.status !== "running") {
+    return {
+      stopped: cancelled > 0,
+      message: `${cancelledText}流水线当前没有在运行（${describeStatus(state, input.featureDir).split("\n")[1]}）。`,
+    };
+  }
+
+  const wasAlive = isAlive(state.pid);
+  if (wasAlive) {
+    try {
+      process.kill(state.pid, "SIGTERM");
+    } catch {
+      // Already gone.
+    }
+    for (let i = 0; i < 20 && isAlive(state.pid); i++) await input.sleep(250);
+    if (isAlive(state.pid)) {
+      try {
+        process.kill(state.pid, "SIGKILL");
+      } catch {
+        // Already gone.
+      }
+    }
+  }
+
+  // Re-read: on POSIX the pipeline records its own shutdown before exiting.
+  const latest = readState(input.statePath) ?? state;
+  const interrupted = latest.history.filter((h) => h.outcome === "running" || (h.endedAt === null && h.agentId));
+  for (const record of interrupted) {
+    record.outcome = "failed";
+    record.endedAt = new Date().toISOString();
+    record.error = "被手动停止";
+  }
+  latest.status = "failed";
+  latest.stopReason = wasAlive ? "已被手动停止" : "后台进程已意外退出";
+  writeState(input.statePath, latest);
+
+  // The step agent keeps working unless told otherwise; stop it so it changes nothing more.
+  if (interrupted.some((r) => r.agentId)) {
+    try {
+      const runtime = await input.createRuntime({ config: input.config, log: input.log });
+      for (const record of interrupted) {
+        if (!record.agentId) continue;
+        await runtime
+          .interruptAgent(
+            record.agentId,
+            "开发流水线已被用户停止。请立即停止当前工作，不要再修改任何文件，也不要写结果文件，直接结束。",
+          )
+          .catch((error: Error) => input.log(`无法停止 agent ${record.agentId}：${error.message}`));
+      }
+      await runtime.close().catch(() => undefined);
+    } catch (error) {
+      input.log(`无法连接 Paseo 停止当前步骤的 agent：${(error as Error).message}`);
+    }
+  }
+
+  const where = interrupted.length > 0 ? `，停在「${stepName(interrupted[0])}」` : "";
+  return {
+    stopped: true,
+    message: wasAlive
+      ? `流水线已停止${where}。已完成的步骤会保留，之后可以用 --resume 从这里继续。`
+      : `流水线的后台进程已经意外退出${where}，状态已更新。可以用 --resume 继续。`,
+  };
+}
+
+/**
+ * What the running step agents did most recently, read from Paseo. Empty when the
+ * pipeline is not running or the daemon cannot be reached within `timeoutMs`.
+ */
+export async function describeLiveActivity(
+  state: PipelineState | null,
+  runtime: Pick<AgentRuntime, "recentActivity">,
+  timeoutMs = 8000,
+  now = new Date(),
+): Promise<string[]> {
+  if (!state || state.status !== "running" || !isAlive(state.pid)) return [];
+  const running = state.history.filter((h) => h.attempt === state.attempt && h.outcome === "running" && h.agentId).slice(0, 3);
+  const lines: string[] = [];
+  for (const record of running) {
+    const items = await Promise.race([
+      runtime.recentActivity(record.agentId, 5).catch(() => null),
+      new Promise<null>((resolve) => setTimeout(() => resolve(null), timeoutMs).unref()),
+    ]);
+    if (!items || items.length === 0) continue;
+    lines.push(`「${stepName(record)}」的 agent 最近在做：`, ...describeActivity(items, now));
+  }
+  return lines;
+}

package/engine/src/daemon-check.ts

@@ -0,0 +1,104 @@
+// Checks against the real Paseo daemon, shared by the smoke test and the doctor.
+
+import type { AgentProfile, PipelineConfig } from "./config.js";
+import { profilesFromDaemonConfig, resolveConfigProfiles, usesPaseoProfiles } from "./paseo-profiles.js";
+
+export type Report = (level: "ok" | "warn" | "fail", text: string, fix?: string) => void;
+
+export async function connect(config: PipelineConfig) {
+  const { createPaseoClient } = await import("@getpaseo/client");
+  const password = process.env[config.daemonPasswordEnv];
+  const client = createPaseoClient({ url: config.daemonUrl, ...(password ? { password } : {}) });
+  await client.connect();
+  return client;
+}
+
+export type Client = Awaited<ReturnType<typeof connect>>;
+
+/** The config with Paseo profile names resolved against this daemon. Throws ProfileResolutionError. */
+export async function resolveWithDaemon(client: Client, config: PipelineConfig): Promise<PipelineConfig> {
+  if (!usesPaseoProfiles(config)) return config;
+  const daemonConfig = await client.config.get().then((r) => r.config).catch(() => null);
+  return resolveConfigProfiles(config, daemonConfig ? profilesFromDaemonConfig(daemonConfig) : null);
+}
+
+/** Checks that a role's provider, model and mode exist and will not stop for approvals. */
+export async function checkProfile(client: Client, role: string, profile: AgentProfile, report: Report): Promise<boolean> {
+  const full = profile.provider ?? "";
+  const slash = full.indexOf("/");
+  const provider = full.slice(0, slash);
+  const model = full.slice(slash + 1);
+  const where = `~/.req-kit/config.json 的 agents.${role}`;
+  let ok = true;
+  try {
+    const models = await client.providers.listModels(provider);
+    const ids = (models.models ?? []).map((m) => m.id);
+    if (ids.includes(model)) {
+      report("ok", `${role}：模型 ${profile.provider}`);
+    } else {
+      ok = false;
+      report("fail", `${role}：模型 ${profile.provider} 在 daemon 中不存在`, `修改 ${where}.provider。可用：${ids.map((id) => `${provider}/${id}`).join(", ") || "（无）"}`);
+    }
+  } catch (error) {
+    report("fail", `${role}：无法列出 ${provider} 的模型：${(error as Error).message}`, `确认 Paseo 中已安装并登录 ${provider}`);
+    return false;
+  }
+  // Some providers (e.g. Pi) have no modes and never stop for approvals; they need no modeId.
+  try {
+    const modes = await client.providers.listModes(provider);
+    const ids = (modes.modes ?? []).map((m) => m.id);
+    if (ids.length === 0) {
+      if (profile.modeId) {
+        ok = false;
+        report("fail", `${role}：${provider} 没有模式，但配置了 modeId（${profile.modeId}）`, `删除 ${where}.modeId`);
+      } else {
+        report("ok", `${role}：${provider} 没有模式，不需要 modeId`);
+      }
+    } else if (!profile.modeId) {
+      ok = false;
+      report("fail", `${role}：没有设置 modeId，agent 可能会停下来等待权限批准`, `设置 ${where}.modeId，可用：${ids.join(", ")}`);
+    } else if (!ids.includes(profile.modeId)) {
+      ok = false;
+      report("fail", `${role}：模式 ${profile.modeId} 不存在`, `修改 ${where}.modeId，可用：${ids.join(", ")}`);
+    } else if (provider === "opencode" && profile.featureValues?.auto_accept !== true) {
+      ok = false;
+      report("fail", `${role}：OpenCode 没有开启自动接受，会停下来等待权限批准`, `在 ${where} 中加上 "featureValues": { "auto_accept": true }`);
+    } else {
+      report("ok", `${role}：模式 ${profile.modeId}`);
+    }
+  } catch (error) {
+    ok = false;
+    report("fail", `${role}：无法列出 ${provider} 的模式：${(error as Error).message}`);
+  }
+  return ok;
+}
+
+/** Minimal "x.y.z satisfies '>=a.b.c <d.e.f'" for the ranges req-kit declares. */
+export function satisfies(version: string, range: string): boolean {
+  const parse = (v: string) => v.replace(/^v/, "").split(/[-+]/)[0].split(".").map((n) => Number(n) || 0);
+  const cmp = (a: number[], b: number[]) => {
+    for (let i = 0; i < 3; i += 1) if ((a[i] ?? 0) !== (b[i] ?? 0)) return (a[i] ?? 0) - (b[i] ?? 0);
+    return 0;
+  };
+  const v = parse(version);
+  return range
+    .trim()
+    .split(/\s+/)
+    .every((part) => {
+      const match = /^(>=|<=|>|<|=)?(.+)$/.exec(part);
+      if (!match) return false;
+      const c = cmp(v, parse(match[2]));
+      switch (match[1] ?? "=") {
+        case ">=":
+          return c >= 0;
+        case "<=":
+          return c <= 0;
+        case ">":
+          return c > 0;
+        case "<":
+          return c < 0;
+        default:
+          return c === 0;
+      }
+    });
+}

package/engine/src/daemon-version.ts

@@ -0,0 +1,66 @@
+// Prints the version of the Paseo daemon this machine uses (one line), for the
+// installer's version choice: node <tsx> engine/src/daemon-version.ts [--config <file>]
+// Exit code 1 and nothing on stdout when it cannot be read.
+
+import fs from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { DEFAULT_CONFIG } from "./config.js";
+import { defaultConfigPath } from "./locations.js";
+
+interface ServerInfoClient {
+  connect(): Promise<void>;
+  close(): Promise<void>;
+  getLastServerInfoMessage(): { version?: string | null } | null | undefined;
+}
+
+export async function daemonVersion(daemonUrl: string, password: string | undefined, timeoutMs = 8000): Promise<string | null> {
+  const internal = (await import("@getpaseo/client/internal/daemon-client").catch(() => null)) as {
+    DaemonClient?: new (options: Record<string, unknown>) => ServerInfoClient;
+  } | null;
+  if (!internal?.DaemonClient) return null;
+  const client = new internal.DaemonClient({
+    url: daemonUrl,
+    clientId: `req-kit-version-${process.pid}`,
+    clientType: "cli",
+    connectTimeoutMs: timeoutMs,
+    ...(password ? { password } : {}),
+  });
+  try {
+    await client.connect();
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      const version = client.getLastServerInfoMessage()?.version;
+      if (version) return version;
+      if (Date.now() > deadline) return null;
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  } finally {
+    await client.close().catch(() => undefined);
+  }
+}
+
+async function main(): Promise<number> {
+  const { values } = parseArgs({ args: process.argv.slice(2), options: { config: { type: "string" } } });
+  const file = values.config ? path.resolve(values.config) : defaultConfigPath();
+  let url = DEFAULT_CONFIG.daemonUrl;
+  let passwordEnv = DEFAULT_CONFIG.daemonPasswordEnv;
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, "utf8")) as { daemonUrl?: string; daemonPasswordEnv?: string };
+    url = raw.daemonUrl ?? url;
+    passwordEnv = raw.daemonPasswordEnv ?? passwordEnv;
+  } catch {
+    // No machine config yet: the default address.
+  }
+  const version = await daemonVersion(url, process.env[passwordEnv]).catch(() => null);
+  if (!version) return 1;
+  console.log(version);
+  return 0;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(import.meta.filename)) {
+  main().then(
+    (code) => process.exit(code),
+    () => process.exit(1),
+  );
+}