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

package/engine/src/preflight.ts

@@ -0,0 +1,298 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import {
+  type DefectHandling,
+  PHASE_MODE_LABELS,
+  PHASE_MODES,
+  type PhaseMode,
+  PROFILE_LABELS,
+  PROFILE_NAMES,
+  type ProfileName,
+  type VerifyEnvironment,
+} from "./config.js";
+import { gitInfo } from "./git.js";
+import { samePath } from "./paths.js";
+import { currentLockHolder, type PipelineState, readState, statePath } from "./state.js";
+
+export interface LaunchArgs {
+  repo: string;
+  featureDir: string;
+  originAgentId: string | null;
+  resume: boolean;
+  restart: boolean;
+  configPath: string | null;
+  /** Explicit --profile; otherwise the spec's "档位" line, then the configured default. */
+  profile: ProfileName | null;
+  status: boolean;
+  stop: boolean;
+  /** --list: print every requirement in this repository's worktrees. */
+  list: boolean;
+  /** --spec-review: independent review of the draft spec, before confirmation. */
+  specReview: boolean;
+  /** --worktree: create a Paseo worktree workspace for this requirement and develop there. */
+  worktree: boolean;
+  /**
+   * The checkout the chat works in, when the pipeline runs in a worktree created for it
+   * (repo is then that worktree). Set by the launcher; the chat's cwd must be this.
+   */
+  sourceRepo: string | null;
+  /** Paseo workspace of that worktree. */
+  workspaceId: string | null;
+  /** --at: schedule the start for later instead of starting now. */
+  at: string | null;
+  /** --phases: execution mode for this run; otherwise the spec's "执行方式" line, then the config. */
+  phases: PhaseMode | null;
+  /** --phase verify: start (or continue) the verify phase. Implies --resume. */
+  phase: "verify" | null;
+  /** --verify-at: once development is done, start the verify phase at this time. */
+  verifyAt: string | null;
+  /** --verify-env: where the verify phase checks the result (overrides phases.verify.environment). */
+  verifyEnv: VerifyEnvironment | null;
+  /** --defects: what the verify phase does with defects (overrides phases.verify.defects). */
+  defects: DefectHandling | null;
+}
+
+export class PreflightError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PreflightError";
+  }
+}
+
+function gitCommonDir(dir: string): string | null {
+  try {
+    const out = execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
+      cwd: dir,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    return out ? fs.realpathSync(out) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Whether `worktree` is a git worktree of the same repository as `source`. */
+export function sameRepository(worktree: string, source: string): boolean {
+  const a = gitCommonDir(worktree);
+  const b = gitCommonDir(source);
+  return a !== null && b !== null && samePath(a, b);
+}
+
+/**
+ * Step agents run under the launching chat. Normally they work in the chat's own
+ * directory, so the repository must be it. A requirement developed in a worktree
+ * created for it (--worktree) runs in that worktree instead; the chat must then be
+ * in the checkout the worktree was created from.
+ */
+export function checkChatCwd(args: Pick<LaunchArgs, "originAgentId" | "sourceRepo">, repo: string, env: NodeJS.ProcessEnv = process.env): void {
+  const chatCwd = env.PASEO_AGENT_CWD?.trim();
+  if (!args.originAgentId || !chatCwd || env.PASEO_AGENT_ID?.trim() !== args.originAgentId) return;
+  const chat = fs.existsSync(chatCwd) ? fs.realpathSync(chatCwd) : chatCwd;
+  if (args.sourceRepo) {
+    const source = fs.existsSync(args.sourceRepo) ? fs.realpathSync(args.sourceRepo) : args.sourceRepo;
+    if (samePath(chat, source) && sameRepository(repo, source)) return;
+    throw new PreflightError(
+      `这个需求在为它新建的工作区 ${repo} 中开发，只能从 ${source} 的对话中操作，当前对话的工作目录是 ${chatCwd}。`,
+    );
+  }
+  if (!samePath(chat, repo)) {
+    throw new PreflightError(
+      `仓库目录 ${repo} 与当前对话的工作目录 ${chatCwd} 不一致。` +
+        "流水线的步骤会挂在这个对话下、在对话的工作目录中进行，所以只能为对话所在的项目启动。" +
+        "请在该仓库对应的项目中打开对话后再启动；对话过程中不要切换工作目录。",
+    );
+  }
+}
+
+/** The spec must carry the line written by the kickoff skill after the user confirms it. */
+export function isSpecConfirmed(specText: string): boolean {
+  return /^\s*-\s*状态\s*[:：]\s*已确认/m.test(specText);
+}
+
+export function normalizeFeatureDir(repo: string, featureDir: string): string {
+  const absolute = path.resolve(repo, featureDir);
+  const relative = path.relative(repo, absolute);
+  if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new PreflightError(`功能目录必须位于仓库目录之内：${featureDir}`);
+  }
+  return relative.split(path.sep).join("/");
+}
+
+export type StartMode =
+  | { kind: "fresh" }
+  | { kind: "restart"; previous: PipelineState }
+  | { kind: "resume-reuse"; previous: PipelineState }
+  | { kind: "resume-from-design"; previous: PipelineState; reason: string };
+
+export interface PreflightResult {
+  repo: string;
+  featureDir: string;
+  specPath: string;
+  mode: StartMode;
+  /** Branch the run will commit to; null outside a git repository. */
+  branch: string | null;
+  /** Profile named in the spec, if any. */
+  specProfile: ProfileName | null;
+  /** Execution mode named in the spec, if any. */
+  specPhases: PhaseMode | null;
+  /** This start begins the verify phase (the develop phase is done). */
+  entersVerify: boolean;
+}
+
+/** Reads "- 执行方式：分阶段" (连续 / 分阶段 / 只做研发, or the English names) from the spec header. */
+export function specPhases(specText: string): PhaseMode | null {
+  const match = /^\s*-\s*执行方式\s*[:：]\s*(\S+)/m.exec(specText);
+  if (!match) return null;
+  for (const mode of PHASE_MODES) {
+    if (match[1].startsWith(PHASE_MODE_LABELS[mode]) || match[1].toLowerCase().startsWith(mode)) return mode;
+  }
+  return null;
+}
+
+/** Whether a run has finished its develop phase, so the verify phase can start. */
+export function developDone(state: PipelineState): boolean {
+  return state.status === "phase_done" || (state.status === "completed" && state.phases?.mode === "develop-only");
+}
+
+/** Reads "- 档位：快速" / "- 档位：标准" from the spec header. */
+export function specProfile(specText: string): ProfileName | null {
+  const match = /^\s*-\s*档位\s*[:：]\s*(\S+)/m.exec(specText);
+  if (!match) return null;
+  for (const name of PROFILE_NAMES) {
+    if (match[1].startsWith(PROFILE_LABELS[name]) || match[1].toLowerCase().startsWith(name)) return name;
+  }
+  return null;
+}
+
+/**
+ * Checks everything that can be checked without talking to the daemon.
+ * The launcher runs this before detaching so the chat agent gets an immediate,
+ * readable error; the pipeline process runs it again before taking the lock.
+ */
+export function preflight(
+  args: LaunchArgs,
+  currentSpecHash: (file: string) => string,
+  env: NodeJS.ProcessEnv = process.env,
+): PreflightResult {
+  if (!fs.existsSync(args.repo) || !fs.statSync(args.repo).isDirectory()) {
+    throw new PreflightError(`仓库目录不存在：${args.repo}`);
+  }
+  const repo = fs.realpathSync(args.repo);
+  checkChatCwd(args, repo, env);
+  const featureDir = normalizeFeatureDir(repo, args.featureDir);
+  const featureAbs = path.join(repo, featureDir);
+  if (!fs.existsSync(featureAbs) || !fs.statSync(featureAbs).isDirectory()) {
+    throw new PreflightError(`功能目录不存在：${featureDir}`);
+  }
+  const specPath = path.join(featureAbs, "spec.md");
+  if (!fs.existsSync(specPath)) {
+    throw new PreflightError(`功能目录中没有 spec.md：${featureDir}`);
+  }
+  const specText = fs.readFileSync(specPath, "utf8");
+  if (!isSpecConfirmed(specText)) {
+    throw new PreflightError(
+      'spec.md 还没有被确认（顶部需要有 "- 状态：已确认" 这一行）。请先和用户确认需求说明。',
+    );
+  }
+  if (args.resume && args.restart) {
+    throw new PreflightError("--resume 和 --restart 不能同时使用");
+  }
+
+  const holder = currentLockHolder(repo);
+  if (holder) {
+    throw new PreflightError(
+      `这个仓库目录已有一条流水线在运行（进程 ${holder.pid}，功能目录 ${holder.featureDir}）。同一个目录一次只能运行一条。`,
+    );
+  }
+
+  const previous = readState(statePath(repo, featureDir));
+  let mode: StartMode;
+  if (!previous) {
+    if (args.resume) throw new PreflightError("没有找到之前的运行记录，无法继续。去掉 --resume 重新启动即可。");
+    mode = { kind: "fresh" };
+  } else if (args.restart) {
+    mode = { kind: "restart", previous };
+  } else if (!args.resume) {
+    const hint =
+      previous.status === "phase_done"
+        ? "这个需求的研发阶段已经完成，正在等待测试验证。开始测试验证请加 --resume --phase verify（或只加 --resume）；要从头开始请加 --restart。"
+        : previous.status === "completed"
+        ? "这个需求的流水线已经完成。如需重新完整运行，请加 --restart。"
+        : `这个需求已有运行记录（状态：${previous.status}）。从中断处继续请加 --resume，从头开始请加 --restart。`;
+    throw new PreflightError(hint);
+  } else if (args.phase === "verify" && !developDone(previous) && previous.phase !== "verify") {
+    throw new PreflightError(
+      previous.status === "completed"
+        ? "这个需求已经完整走完了研发和测试验证，没有单独的测试阶段可以开始。要重新验证，请更新需求说明后用 --resume，或用 --restart。"
+        : `这个需求的研发阶段还没有完成（状态：${previous.status}），还不能开始测试验证。请先用 --resume 继续研发。`,
+    );
+  } else if (args.phase === "verify" && developDone(previous) && currentSpecHash(specPath) === previous.specHash) {
+    // Development is done and the requirement has not changed since: the verify phase starts.
+    mode = { kind: "resume-reuse", previous };
+  } else if (previous.status === "phase_done" && currentSpecHash(specPath) === previous.specHash) {
+    // A plain --resume at the gate starts the verify phase too.
+    mode = { kind: "resume-reuse", previous };
+  } else if (previous.status === "completed") {
+    // A completed requirement is reopened by changing its spec (a requirement change, or
+    // problems found during acceptance). Without such a change there is nothing to continue.
+    if (currentSpecHash(specPath) === previous.specHash) {
+      if (previous.phases?.mode === "develop-only") {
+        throw new PreflightError(
+          "这个需求按\"只做研发\"完成了研发，没有可继续的步骤。要让流水线做测试验证，请用 --resume --phase verify；要修改需求，请先更新并重新确认 spec.md。",
+        );
+      }
+      throw new PreflightError(
+        "这个需求的流水线已经完成，没有可继续的步骤。要修改需求或修复验收中发现的问题，请先更新并重新确认 spec.md；要原样重跑一遍，请用 --restart。",
+      );
+    }
+    mode = { kind: "resume-from-design", previous, reason: "流水线完成后 spec.md 被修改过（需求变更或验收发现的问题），从方案设计开始增量处理" };
+  } else if (previous.status === "waiting_for_business") {
+    mode = { kind: "resume-from-design", previous, reason: "上次因等待需求方决定而停止，需求可能已更新，从方案设计开始增量处理" };
+  } else if (currentSpecHash(specPath) !== previous.specHash) {
+    mode = { kind: "resume-from-design", previous, reason: "spec.md 在上次运行后被修改过，从方案设计开始增量处理" };
+  } else {
+    // "failed", or "running" left behind by a process that died without cleanup.
+    mode = { kind: "resume-reuse", previous };
+  }
+  const git = gitInfo(repo);
+  if (args.worktree) {
+    // The run will happen in a new worktree on its own branch, cut from what is checked out here.
+    if (mode.kind !== "fresh") {
+      throw new PreflightError("这个需求已经在这里运行过，不能再改为在新工作区中开发。请用 --resume 继续，或去掉 --worktree。");
+    }
+    if (!git.isRepo) throw new PreflightError("--worktree 需要 git 仓库。");
+    return { repo, featureDir, specPath, mode, branch: git.branch, specProfile: specProfile(specText), specPhases: specPhases(specText), entersVerify: false };
+  }
+  // The run commits to the branch that is checked out now, and never to the default branch.
+  if (git.isRepo && git.detached) {
+    throw new PreflightError("当前没有处在任何分支上（detached HEAD）。请切换到这个需求的工作分支后再启动。");
+  }
+  if (git.branch && git.protectedBranches.includes(git.branch)) {
+    throw new PreflightError(
+      `当前在默认分支 ${git.branch} 上，流水线不会在默认分支上提交代码。` +
+        "可以加 --worktree，让流水线为这个需求新建一个 worktree 工作区并在那里开发（这个对话不用动）；" +
+        "或者在 Paseo 中自己新建一个 worktree 工作区（New workspace → Isolation 选 New worktree），在那里的对话中重新开始；" +
+        "或者先切换到这个需求的功能分支。",
+    );
+  }
+  if (mode.kind === "resume-reuse" && mode.previous.branch && git.branch !== mode.previous.branch) {
+    throw new PreflightError(
+      `这个需求之前在分支 ${mode.previous.branch} 上进行，现在的分支是 ${git.branch ?? "（无）"}。请切回原分支后继续，或用 --restart 在当前分支上从头开始。`,
+    );
+  }
+  const entersVerify = mode.kind === "resume-reuse" && developDone(mode.previous);
+  return { repo, featureDir, specPath, mode, branch: git.branch, specProfile: specProfile(specText), specPhases: specPhases(specText), entersVerify };
+}
+
+/** Why the verify phase cannot start in this environment, or null. */
+export function verifyPhaseProblem(repo: string, featureDir: string, environment: VerifyEnvironment): string | null {
+  if (environment !== "deployed") return null;
+  if (fs.existsSync(path.join(repo, featureDir, "test-env.md"))) return null;
+  return (
+    `要在已部署的测试环境中验证，但功能目录中还没有 test-env.md（${featureDir}/test-env.md）。` +
+    "请先和用户确认测试环境，写好这个文件（地址、账号从哪里取、可以用的测试数据和账号；只写口令在哪里取，不写口令本身），再开始测试验证；" +
+    "或者用 --verify-env local 在本地验证。"
+  );
+}

package/engine/src/prompts.ts

@@ -0,0 +1,72 @@
+import fs from "node:fs";
+import path from "node:path";
+
+// Prompt sources, from least to most specific:
+//   <kit>/engine/prompts/<file>                    shipped with this version
+//   <kit home>/prompts.local/<file>                machine-wide override; replaces the shipped file, survives upgrades
+//   <kit>/principles/INDEX.md                      principles, also read by the chat skills
+//   <repo>/.requirement-pipeline/project-notes.md  appended to every step of this project
+//   <repo>/.requirement-pipeline/verify.md         appended to the steps that build, start or test the project
+//   <repo>/.requirement-pipeline/steps/<step>.md   appended to one step of this project
+
+export const PROJECT_DIR = ".requirement-pipeline";
+
+export interface PromptLocations {
+  promptsDir: string;
+  localPromptsDir: string;
+  principlesFile: string;
+}
+
+export interface PromptSources extends PromptLocations {
+  repo: string;
+}
+
+export function readToolPrompt(sources: PromptSources, file: string): string {
+  const local = path.join(sources.localPromptsDir, file);
+  const shipped = path.join(sources.promptsDir, file);
+  return fs.readFileSync(fs.existsSync(local) ? local : shipped, "utf8").trim();
+}
+
+/** The shared principles, as a prompt section, or null when the index is missing. */
+export function principlesSection(sources: PromptSources): string | null {
+  const text = readIfPresent(sources.principlesFile);
+  if (!text) return null;
+  // The index starts with its own title; give it a heading that fits inside the prompt.
+  const body = text.replace(/^#\s+.*\n+/, "");
+  return ["# 工作原则", "", "以下原则在需求对齐阶段和流水线各步骤中通用。具体要求以前文和\"本步骤任务\"为准，这里说明背后的取舍。", "", body].join("\n");
+}
+
+function readIfPresent(file: string): string | null {
+  if (!fs.existsSync(file)) return null;
+  const text = fs.readFileSync(file, "utf8").trim();
+  return text === "" ? null : text;
+}
+
+/** Steps that build, start or test the project, and so need the project's verification instructions. */
+export const VERIFY_STEPS: readonly string[] = ["implement", "review_fix", "service_start", "verify", "defect_fix", "reverify"];
+
+/** Project-specific additions for one step, ready to append, or null when there are none. */
+export function projectAdditions(sources: PromptSources, stepId: string): string | null {
+  const notes = readIfPresent(path.join(sources.repo, PROJECT_DIR, "project-notes.md"));
+  const verify = VERIFY_STEPS.includes(stepId) ? readIfPresent(path.join(sources.repo, PROJECT_DIR, "verify.md")) : null;
+  const step = readIfPresent(path.join(sources.repo, PROJECT_DIR, "steps", `${stepId}.md`));
+  if (!notes && !verify && !step) return null;
+  const parts = [
+    "# 本项目的补充说明",
+    "",
+    "以下内容由项目维护者编写，说明这个项目的约定和要求。与前文的通用要求冲突时，以这里为准；但\"如实报告\"和安全方面的要求始终有效。",
+  ];
+  if (notes) parts.push("", notes);
+  if (verify) {
+    parts.push(
+      "",
+      "## 本项目的验证方法",
+      "",
+      "来自 `.requirement-pipeline/verify.md`，其中的命令已由项目维护者实际运行过。安装依赖、启动服务、运行测试时优先照此执行；发现它过时或不准确时，照常完成本步骤，并在你的产物里写明哪里不对、实际可行的做法是什么。",
+      "",
+      verify,
+    );
+  }
+  if (step) parts.push("", "## 针对本步骤", "", step);
+  return parts.join("\n");
+}

package/engine/src/queue.ts

@@ -0,0 +1,61 @@
+// Machine-wide limit on pipelines running at once (maxConcurrentPipelines).
+// A pipeline takes one of N slot files in ~/.req-kit/slots; creating a file with "wx"
+// is atomic, so two pipelines starting together cannot both take the last slot.
+// A slot whose process is gone is free again.
+
+import fs from "node:fs";
+import path from "node:path";
+import { kitHome } from "./locations.js";
+import { isAlive } from "./state.js";
+
+export interface SlotHolder {
+  pid: number;
+  repo: string;
+  featureDir: string;
+  since: string;
+}
+
+export function slotsDir(env: NodeJS.ProcessEnv = process.env): string {
+  return path.join(kitHome(env), "slots");
+}
+
+function readHolder(file: string): SlotHolder | null {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8")) as SlotHolder;
+  } catch {
+    return null;
+  }
+}
+
+/** Pipelines holding a slot now (dead holders are cleared on the way). */
+export function slotHolders(dir: string): SlotHolder[] {
+  if (!fs.existsSync(dir)) return [];
+  const holders: SlotHolder[] = [];
+  for (const name of fs.readdirSync(dir)) {
+    const file = path.join(dir, name);
+    const holder = readHolder(file);
+    if (holder && isAlive(holder.pid)) holders.push(holder);
+    else fs.rmSync(file, { force: true });
+  }
+  return holders;
+}
+
+/** Takes a free slot; returns a release function, or null when all `max` slots are taken. */
+export function tryAcquireSlot(dir: string, max: number, holder: SlotHolder): (() => void) | null {
+  fs.mkdirSync(dir, { recursive: true });
+  for (let i = 0; i < max; i++) {
+    const file = path.join(dir, `slot-${i}.json`);
+    const current = readHolder(file);
+    if (current && current.pid !== holder.pid && isAlive(current.pid)) continue;
+    if (current) fs.rmSync(file, { force: true });
+    try {
+      fs.writeFileSync(file, JSON.stringify(holder), { flag: "wx" });
+    } catch {
+      continue; // taken a moment ago by another pipeline
+    }
+    return () => {
+      if (readHolder(file)?.pid === holder.pid) fs.rmSync(file, { force: true });
+    };
+  }
+  return null;
+}

package/engine/src/runtime-loader.ts

@@ -0,0 +1,14 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { RuntimeFactory } from "./runtime.js";
+
+export async function loadRuntimeFactory(): Promise<RuntimeFactory> {
+  // Test hook: run the real orchestration against a scripted fake daemon.
+  const fake = process.env.REQ_PIPELINE_FAKE_RUNTIME;
+  if (fake) {
+    const module = (await import(pathToFileURL(path.resolve(fake)).href)) as { createRuntime: RuntimeFactory };
+    return module.createRuntime;
+  }
+  const module = await import("./paseo-runtime.js");
+  return module.createRuntime;
+}

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" });
+}