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

package/engine/src/paseo-profiles.ts

@@ -0,0 +1,133 @@
+// Paseo agent profiles: named launch bundles (provider, model, mode, thinking level,
+// features) that people set up once in Paseo's settings. req-kit roles and review
+// panel members can name one instead of spelling the settings out:
+//
+//   "builder": { "paseoProfile": "实现" }
+//   "reviewer": { "paseoProfile": "评审", "thinkingOptionId": "high" }   // own fields win
+//
+// The names are resolved against the daemon when a run starts, so changing the
+// profile in Paseo changes the next run without touching req-kit's config.
+
+import type { AgentProfile, PipelineConfig } from "./config.js";
+
+/** The fields of Paseo's AgentProfile that req-kit uses (protocol/src/agent-profile.ts). */
+export interface PaseoProfile {
+  id: string;
+  name: string;
+  provider: string;
+  model?: string;
+  modeId?: string;
+  thinkingOptionId?: string;
+  featureValues?: Record<string, unknown>;
+  notes?: string;
+}
+
+export class ProfileResolutionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ProfileResolutionError";
+  }
+}
+
+export function findPaseoProfile(name: string, available: PaseoProfile[]): PaseoProfile | null {
+  const wanted = name.trim();
+  return (
+    available.find((p) => p.name === wanted) ??
+    available.find((p) => p.name.toLowerCase() === wanted.toLowerCase()) ??
+    available.find((p) => p.id === wanted) ??
+    null
+  );
+}
+
+/**
+ * Turns a role that names a Paseo profile into concrete agent settings. Settings
+ * written next to `paseoProfile` override the profile's; feature values are merged.
+ * Roles without `paseoProfile` are returned unchanged.
+ */
+export function resolveAgentProfile(label: string, profile: AgentProfile, available: PaseoProfile[] | null): AgentProfile {
+  if (!profile.paseoProfile) return profile;
+  if (available === null) {
+    throw new ProfileResolutionError(`${label} 使用 Paseo profile「${profile.paseoProfile}」，但无法从 daemon 读取 profile 列表`);
+  }
+  const found = findPaseoProfile(profile.paseoProfile, available);
+  if (!found) {
+    const names = available.map((p) => `「${p.name}」`).join("、") || "（还没有任何 profile）";
+    throw new ProfileResolutionError(
+      `${label} 使用的 Paseo profile「${profile.paseoProfile}」不存在。现有的 profile：${names}。在 Paseo 的 设置 → Agents → Agent profiles 中查看或新建`,
+    );
+  }
+  if (!found.model) {
+    throw new ProfileResolutionError(`Paseo profile「${found.name}」没有选择模型，req-kit 需要明确的模型。请在 Paseo 设置中为它选择模型`);
+  }
+  const resolved: AgentProfile = { ...profile, provider: profile.provider ?? `${found.provider}/${found.model}` };
+  const modeId = profile.modeId ?? found.modeId;
+  const thinking = profile.thinkingOptionId ?? found.thinkingOptionId;
+  const features = found.featureValues || profile.featureValues ? { ...found.featureValues, ...profile.featureValues } : undefined;
+  if (modeId) resolved.modeId = modeId;
+  if (thinking) resolved.thinkingOptionId = thinking;
+  if (features) resolved.featureValues = features;
+  return resolved;
+}
+
+/** "Paseo profile「实现」→ claude/opus（模式 bypassPermissions）" */
+export function describeAgentProfile(profile: AgentProfile): string {
+  if (!profile.provider) return `Paseo profile「${profile.paseoProfile}」（运行时从 Paseo 读取设置）`;
+  const settings = `${profile.provider}${profile.modeId ? `（模式 ${profile.modeId}）` : ""}`;
+  return profile.paseoProfile ? `Paseo profile「${profile.paseoProfile}」→ ${settings}` : settings;
+}
+
+/** Reads the daemon's profiles from its config. Null when the daemon does not say. */
+export function profilesFromDaemonConfig(config: unknown): PaseoProfile[] | null {
+  if (typeof config !== "object" || config === null) return null;
+  const list = (config as { agentProfiles?: unknown }).agentProfiles;
+  if (list === undefined) return [];
+  if (!Array.isArray(list)) return null;
+  return list.filter(
+    (p): p is PaseoProfile =>
+      typeof p === "object" && p !== null && typeof (p as PaseoProfile).name === "string" && typeof (p as PaseoProfile).provider === "string",
+  );
+}
+
+/** Whether any role or panel member names a Paseo profile. */
+export function usesPaseoProfiles(config: PipelineConfig): boolean {
+  return [
+    config.agents.builder,
+    config.agents.reviewer,
+    ...config.reviewPanel.members,
+    ...config.designProposals.members,
+    ...Object.values(config.phases.verify.agents),
+  ].some((p) =>
+    Boolean(p.paseoProfile),
+  );
+}
+
+/** The config with every Paseo profile name replaced by its settings. Throws ProfileResolutionError. */
+export function resolveConfigProfiles(config: PipelineConfig, available: PaseoProfile[] | null): PipelineConfig {
+  return {
+    ...config,
+    agents: {
+      builder: resolveAgentProfile("agents.builder", config.agents.builder, available),
+      reviewer: resolveAgentProfile("agents.reviewer", config.agents.reviewer, available),
+    },
+    reviewPanel: {
+      ...config.reviewPanel,
+      members: config.reviewPanel.members.map((m, i) => ({ ...m, ...resolveAgentProfile(`reviewPanel.members[${i}]`, m, available) })),
+    },
+    designProposals: {
+      ...config.designProposals,
+      members: config.designProposals.members.map((m, i) => ({
+        ...m,
+        ...resolveAgentProfile(`designProposals.members[${i}]`, m, available),
+      })),
+    },
+    phases: {
+      ...config.phases,
+      verify: {
+        ...config.phases.verify,
+        agents: Object.fromEntries(
+          Object.entries(config.phases.verify.agents).map(([role, p]) => [role, resolveAgentProfile(`phases.verify.agents.${role}`, p, available)]),
+        ),
+      },
+    },
+  };
+}

package/engine/src/paseo-runtime.ts

@@ -0,0 +1,437 @@
+import type { PaseoAgentHandle, PaseoClient } from "@getpaseo/client";
+import { summarizeActivity } from "./activity.js";
+import { type AgentProfile, isResolved, type PipelineConfig } from "./config.js";
+import { profilesFromDaemonConfig } from "./paseo-profiles.js";
+import { cronAt, localTimeZone } from "./schedule-time.js";
+import { samePath } from "./paths.js";
+import type { AgentRuntime, ManagedService, ProviderQuota, RuntimeFactory, ServiceTarget, StepAgent, WaitOutcome } from "./runtime.js";
+
+// Checked against @getpaseo/client 0.11.2 (packages/client/src/index.ts) and the
+// daemon (packages/server/src/server/session.ts, agent/create-agent/intent.ts):
+// - agents.create({ config: { provider: "provider/model", modeId }, cwd, title, labels, prompt, parent })
+//   With `parent`, the daemon places the agent in the parent's workspace AND uses the
+//   parent's cwd; the requested cwd is ignored. The pipeline therefore requires the chat's
+//   cwd to be the repository (verifyOrigin), and verifies every created agent's cwd.
+//   SDK-created subagents do not post finish notifications to the parent.
+// - handle.waitForFinish(timeoutMs) -> { status: idle|error|permission|timeout, final, error, lastMessage }
+//   The daemon answers immediately when the agent is already idle or has a pending permission.
+// - handle.send(text, { activeTurnBehavior }) -> the daemon interrupts a running turn
+//   unless activeTurnBehavior is "steer".
+// - config.get() -> { config: { agentProfiles?: AgentProfile[], mcp, browserTools, ... } }
+// - providers.listUsage() -> { providers: [{ providerId, displayName, windows: [{ label, usedPct, resetsAt, tone }] }] }
+// - agent.timeline.refetch({ direction: "tail", limit }) -> { entries: [{ timestamp, item }] }
+// - Workspace scripts (paseo.json) are not on the public client in 0.11; they are reached
+//   through the exported internal DaemonClient (listWorkspaceScripts, startWorkspaceScriptWithStatus,
+//   stopWorkspaceScript). See WorkspaceScripts below; every use degrades to "not available".
+
+export type SdkClient = Pick<PaseoClient, "agents" | "close"> &
+  Partial<Pick<PaseoClient, "config" | "providers" | "terminals" | "workspaces">>;
+
+/** paseo.json scripts as the daemon reports them (protocol WorkspaceScriptPayloadSchema). */
+export interface ScriptInfo {
+  scriptName: string;
+  type?: "script" | "service";
+  port: number | null;
+  proxyUrl?: string | null;
+  localProxyUrl?: string | null;
+  lifecycle: "running" | "stopped";
+  health: "healthy" | "unhealthy" | null;
+  exitCode?: number | null;
+  terminalId?: string | null;
+}
+
+export interface WorkspaceScripts {
+  list(workspaceId: string): Promise<ScriptInfo[]>;
+  start(workspaceId: string, name: string): Promise<void>;
+  stop(workspaceId: string, name: string): Promise<void>;
+  /** paseo.json setup of a new worktree; null when the daemon does not report one. */
+  setupStatus(workspaceId: string): Promise<{ status: "running" | "completed" | "failed" | "blocked"; error: string | null } | null>;
+  /** Paseo schedules (daemon-client scheduleCreate / scheduleDelete). Returns the schedule ID. */
+  createSchedule(options: Record<string, unknown>): Promise<string>;
+  deleteSchedule(id: string): Promise<void>;
+  close(): Promise<void>;
+}
+
+export { samePath };
+
+function agentConfig(profile: AgentProfile) {
+  if (!isResolved(profile)) {
+    throw new Error(`agent 配置没有 provider${profile.paseoProfile ? `（Paseo profile「${profile.paseoProfile}」没有解析）` : ""}`);
+  }
+  return {
+    provider: profile.provider,
+    ...(profile.modeId ? { modeId: profile.modeId } : {}),
+    ...(profile.thinkingOptionId ? { thinkingOptionId: profile.thinkingOptionId } : {}),
+    ...(profile.featureValues ? { featureValues: profile.featureValues } : {}),
+    ...(profile.options ? { options: profile.options as Record<string, never> } : {}),
+  };
+}
+
+function wrap(handle: PaseoAgentHandle): StepAgent {
+  return {
+    id: handle.id,
+    async wait(timeoutMs: number): Promise<WaitOutcome> {
+      const result = await handle.waitForFinish(timeoutMs);
+      const pending = result.final?.pendingPermissions ?? [];
+      return {
+        status: result.status,
+        error: result.error,
+        lastMessage: result.lastMessage,
+        pendingPermissions: pending.map((p) => ({
+          id: p.id,
+          title: p.title ?? p.description ?? p.name,
+        })),
+        usage: result.final?.lastUsage ?? null,
+      };
+    },
+    async followUp(text: string): Promise<void> {
+      await handle.send(text);
+    },
+    async archive(): Promise<void> {
+      await handle.archive();
+    },
+  };
+}
+
+async function agentCwd(handle: PaseoAgentHandle): Promise<string | null> {
+  const fetched = await handle.refresh();
+  return fetched?.agent.cwd ?? null;
+}
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export function createRuntimeWithClient(
+  client: SdkClient,
+  config: PipelineConfig,
+  log: (message: string) => void,
+  scriptsFactory: (() => Promise<WorkspaceScripts | null>) | null = null,
+): AgentRuntime {
+  let scripts: Promise<WorkspaceScripts | null> | null = null;
+  const getScripts = () => {
+    scripts ??= (scriptsFactory ? scriptsFactory() : Promise.resolve(null)).catch((error: Error) => {
+      log(`无法使用 Paseo 的工作区脚本：${error.message}`);
+      return null;
+    });
+    return scripts;
+  };
+  const workspaceOf = async (target: ServiceTarget): Promise<string | null> => {
+    if ("workspaceId" in target) return target.workspaceId;
+    const fetched = await client.agents.ref(target.agentId).refresh().catch(() => null);
+    return fetched?.agent.workspaceId ?? null;
+  };
+  const tail = async (terminalId: string | null | undefined): Promise<string | null> => {
+    if (!terminalId || !client.terminals) return null;
+    try {
+      const captured = await client.terminals.ref(terminalId).capture({ stripAnsi: true });
+      return captured.lines.slice(-60).join("\n").trim() || null;
+    } catch {
+      return null;
+    }
+  };
+  const toService = async (info: ScriptInfo): Promise<ManagedService> => ({
+    name: info.scriptName,
+    url: info.proxyUrl ?? info.localProxyUrl ?? (info.port ? `http://127.0.0.1:${info.port}` : null),
+    port: info.port,
+    running: info.lifecycle === "running",
+    health: info.health ?? null,
+    exitCode: info.exitCode ?? null,
+    output: await tail(info.terminalId),
+  });
+
+  return {
+    async verifyOrigin(agentId, cwd) {
+      let originCwd: string | null;
+      try {
+        originCwd = await agentCwd(client.agents.ref(agentId));
+      } catch (error) {
+        throw new Error(`无法读取发起对话的 agent ${agentId}：${(error as Error).message}`);
+      }
+      if (originCwd === null) {
+        throw new Error(`找不到发起对话的 agent ${agentId}（可能已被归档）。请在需求所在项目的对话中重新启动。`);
+      }
+      if (!samePath(originCwd, cwd)) {
+        throw new Error(
+          `发起对话的工作目录是 ${originCwd}，与仓库目录 ${cwd} 不一致。` +
+            "步骤 agent 会挂在发起的对话下、使用对话的工作目录，所以流水线必须在该仓库对应的项目对话中启动。",
+        );
+      }
+    },
+    async startAgent(input) {
+      const base = {
+        config: agentConfig(input.profile ?? config.agents[input.role]),
+        cwd: input.cwd,
+        title: input.title,
+        labels: input.labels,
+        prompt: input.prompt,
+      };
+      let handle: PaseoAgentHandle;
+      if (input.workspaceId) {
+        // The requirement's own worktree: placed there, still a subagent of the chat.
+        if (!client.workspaces) throw new Error("这个 Paseo 版本不支持把 agent 放进指定的工作区");
+        const { cwd: _cwd, ...placed } = base;
+        handle = await client.workspaces.ref(input.workspaceId).agents.create({
+          ...placed,
+          ...(input.parentAgentId ? { parent: input.parentAgentId } : {}),
+        });
+      } else {
+        handle = input.parentAgentId
+          ? await client.agents.create({ ...base, parent: input.parentAgentId })
+          : await client.agents.create(base);
+      }
+
+      // Guard against the daemon placing the agent anywhere but the repository.
+      const actual = await agentCwd(handle).catch(() => null);
+      if (actual !== null && !samePath(actual, input.cwd)) {
+        await handle.archive().catch(() => undefined);
+        throw new Error(`新建的 agent 工作目录是 ${actual}，不是仓库目录 ${input.cwd}，已停止该 agent`);
+      }
+      return wrap(handle);
+    },
+    async notifyAgent(agentId, text) {
+      await client.agents.ref(agentId).send(text, { activeTurnBehavior: "steer" });
+    },
+    async interruptAgent(agentId, text) {
+      await client.agents.ref(agentId).send(text, { activeTurnBehavior: "interrupt" });
+    },
+    async listPaseoProfiles() {
+      if (!client.config) return null;
+      try {
+        return profilesFromDaemonConfig((await client.config.get()).config);
+      } catch (error) {
+        log(`无法读取 Paseo 的 agent profiles：${(error as Error).message}`);
+        return null;
+      }
+    },
+    async listServices(target) {
+      const api = await getScripts();
+      const workspaceId = api ? await workspaceOf(target) : null;
+      if (!api || !workspaceId) return null;
+      try {
+        const services = (await api.list(workspaceId)).filter((s) => (s.type ?? "service") === "service").map((s) => s.scriptName);
+        return services.length ? services : null;
+      } catch (error) {
+        log(`无法列出工作区脚本：${(error as Error).message}`);
+        return null;
+      }
+    },
+    async startServices(target, names, readyTimeoutMs) {
+      const api = await getScripts();
+      const workspaceId = await workspaceOf(target);
+      if (!api || !workspaceId) throw new Error("无法使用 Paseo 的工作区脚本");
+      const current = await api.list(workspaceId);
+      for (const name of names) {
+        // Stop first so the service runs the code as it is now.
+        if (current.find((s) => s.scriptName === name)?.lifecycle === "running") await api.stop(workspaceId, name);
+        await api.start(workspaceId, name);
+      }
+      const deadline = Date.now() + readyTimeoutMs;
+      let latest = await api.list(workspaceId);
+      for (;;) {
+        const wanted = latest.filter((s) => names.includes(s.scriptName));
+        const settled = wanted.every((s) => s.lifecycle === "stopped" || s.health === "healthy");
+        if (settled || Date.now() >= deadline) break;
+        await sleep(2000);
+        latest = await api.list(workspaceId);
+      }
+      return Promise.all(latest.filter((s) => names.includes(s.scriptName)).map(toService));
+    },
+    async stopServices(target, names) {
+      const api = await getScripts();
+      const workspaceId = await workspaceOf(target);
+      if (!api || !workspaceId) return;
+      const current = await api.list(workspaceId).catch(() => []);
+      for (const name of names) {
+        if (current.find((s) => s.scriptName === name)?.lifecycle !== "running") continue;
+        await api.stop(workspaceId, name).catch((error: Error) => log(`停止服务 ${name} 失败：${error.message}`));
+      }
+    },
+    async providerQuota(providers) {
+      if (!client.providers) return null;
+      try {
+        const usage = await client.providers.listUsage();
+        const quotas: ProviderQuota[] = [];
+        for (const p of usage.providers) {
+          if (!providers.includes(p.providerId) || p.status !== "available") continue;
+          for (const w of p.windows) {
+            quotas.push({
+              provider: p.providerId,
+              displayName: p.displayName,
+              window: w.label,
+              usedPct: w.usedPct ?? (typeof w.remainingPct === "number" ? 100 - w.remainingPct : null),
+              resetsAt: w.resetsAt ?? null,
+              tone: w.tone ?? null,
+            });
+          }
+        }
+        return quotas.length ? quotas : null;
+      } catch {
+        return null;
+      }
+    },
+    async recentActivity(agentId, limit) {
+      try {
+        const page = await client.agents.ref(agentId).timeline.refetch({ direction: "tail", limit: Math.max(limit * 4, 20) });
+        return summarizeActivity(page.entries, limit);
+      } catch {
+        return null;
+      }
+    },
+    async createWorktree(request) {
+      if (!client.workspaces) throw new Error("这个 Paseo 版本不支持新建工作区");
+      const workspace = await client.workspaces.create({
+        source: { kind: "worktree", cwd: request.sourceRepo, action: "branch-off", refName: request.baseRef, branchName: request.branchName },
+        title: request.title,
+        ...(request.callerAgentId ? { callerAgentId: request.callerAgentId } : {}),
+      });
+      const directory = workspace.directory ?? (await workspace.refresh())?.workspaceDirectory ?? null;
+      if (!directory) throw new Error("Paseo 没有返回新工作区的目录");
+      return { workspaceId: workspace.id, directory };
+    },
+    async waitForWorkspaceSetup(workspaceId, timeoutMs) {
+      const api = await getScripts();
+      if (!api) return { status: "none", error: null };
+      const deadline = Date.now() + timeoutMs;
+      for (;;) {
+        const snapshot = await api.setupStatus(workspaceId).catch(() => null);
+        if (!snapshot) return { status: "none", error: null };
+        if (snapshot.status === "completed") return { status: "completed", error: null };
+        if (snapshot.status === "failed" || snapshot.status === "blocked") return { status: "failed", error: snapshot.error ?? snapshot.status };
+        if (Date.now() >= deadline) return { status: "timeout", error: null };
+        await sleep(3000);
+      }
+    },
+    async scheduleMessage(input) {
+      const api = await getScripts();
+      if (!api) return null;
+      const oneShot = input.at !== undefined;
+      return api.createSchedule({
+        name: input.name,
+        prompt: input.prompt,
+        cadence: { type: "cron", expression: oneShot ? cronAt(input.at as Date) : (input.cron as string), timezone: localTimeZone() },
+        target: { type: "agent", agentId: input.agentId },
+        ...(oneShot ? { maxRuns: 1, expiresAt: new Date((input.at as Date).getTime() + 6 * 3600_000).toISOString() } : {}),
+        ...(input.expiresAt ? { expiresAt: input.expiresAt.toISOString() } : {}),
+      });
+    },
+    async scheduleNewAgent(input) {
+      const api = await getScripts();
+      if (!api) return null;
+      const settings = agentConfig(input.profile);
+      const slash = settings.provider.indexOf("/");
+      return api.createSchedule({
+        name: input.name,
+        prompt: input.prompt,
+        cadence: { type: "cron", expression: input.cron, timezone: localTimeZone() },
+        target: {
+          type: "new-agent",
+          config: {
+            provider: settings.provider.slice(0, slash),
+            model: settings.provider.slice(slash + 1),
+            cwd: input.cwd,
+            ...(settings.modeId ? { modeId: settings.modeId } : {}),
+            ...(settings.thinkingOptionId ? { thinkingOptionId: settings.thinkingOptionId } : {}),
+            archiveOnFinish: true,
+            title: input.name,
+          },
+        },
+      });
+    },
+    async cancelSchedule(id) {
+      const api = await getScripts();
+      if (api) await api.deleteSchedule(id);
+    },
+    async capabilities() {
+      if (!client.config) return null;
+      try {
+        const daemonConfig = (await client.config.get()).config as { mcp?: { injectIntoAgents?: boolean }; browserTools?: { enabled?: boolean } };
+        const paseoTools = daemonConfig.mcp?.injectIntoAgents === true;
+        return { paseoTools, browser: paseoTools && daemonConfig.browserTools?.enabled === true };
+      } catch {
+        return null;
+      }
+    },
+    async close() {
+      if (scripts) await (await scripts)?.close().catch(() => undefined);
+      await client.close();
+    },
+  };
+}
+
+export const createRuntime: RuntimeFactory = async ({ config, log }) => {
+  // Loaded lazily so the runtime logic can be tested without the SDK installed.
+  const { createPaseoClient } = await import("@getpaseo/client");
+  const password = process.env[config.daemonPasswordEnv];
+  const client = createPaseoClient({
+    url: config.daemonUrl,
+    ...(password ? { password } : {}),
+    reconnect: { enabled: true },
+  });
+  await client.connect();
+  return createRuntimeWithClient(client, config, log, () => connectScripts(config));
+};
+
+/** Workspace scripts through the internal DaemonClient that @getpaseo/client 0.11 exports. */
+async function connectScripts(config: PipelineConfig): Promise<WorkspaceScripts | null> {
+  const internal = (await import("@getpaseo/client/internal/daemon-client").catch(() => null)) as
+    | { DaemonClient?: new (options: Record<string, unknown>) => InternalDaemonClient }
+    | null;
+  if (!internal?.DaemonClient) return null;
+  const password = process.env[config.daemonPasswordEnv];
+  const daemon = new internal.DaemonClient({
+    url: config.daemonUrl,
+    clientId: `req-kit-${process.pid}-${Date.now().toString(36)}`,
+    clientType: "cli",
+    ...(password ? { password } : {}),
+    reconnect: { enabled: true },
+  });
+  if (typeof daemon.listWorkspaceScripts !== "function") return null;
+  await daemon.connect();
+  const check = (payload: { error: string | null }) => {
+    if (payload.error) throw new Error(payload.error);
+  };
+  return {
+    async list(workspaceId) {
+      const payload = await daemon.listWorkspaceScripts(workspaceId);
+      check(payload);
+      return (payload.scripts ?? []) as ScriptInfo[];
+    },
+    async start(workspaceId, name) {
+      check(await daemon.startWorkspaceScriptWithStatus(workspaceId, name));
+    },
+    async stop(workspaceId, name) {
+      check(await daemon.stopWorkspaceScript(workspaceId, name));
+    },
+    async createSchedule(options) {
+      if (typeof daemon.scheduleCreate !== "function") throw new Error("这个 Paseo 版本不支持定时任务");
+      const payload = await daemon.scheduleCreate(options);
+      if (payload.error || !payload.schedule) throw new Error(payload.error ?? "Paseo 没有返回定时任务");
+      return payload.schedule.id;
+    },
+    async deleteSchedule(id) {
+      if (typeof daemon.scheduleDelete !== "function") return;
+      const payload = await daemon.scheduleDelete({ id });
+      if (payload.error && !/not found/i.test(payload.error)) throw new Error(payload.error);
+    },
+    async setupStatus(workspaceId) {
+      if (typeof daemon.fetchWorkspaceSetupStatus !== "function") return null;
+      const payload = await daemon.fetchWorkspaceSetupStatus(workspaceId);
+      return payload.snapshot ? { status: payload.snapshot.status, error: payload.snapshot.error } : null;
+    },
+    async close() {
+      await daemon.close();
+    },
+  };
+}
+
+interface InternalDaemonClient {
+  connect(): Promise<void>;
+  close(): Promise<void>;
+  listWorkspaceScripts(workspaceId: string): Promise<{ scripts?: unknown[]; error: string | null }>;
+  startWorkspaceScriptWithStatus(workspaceId: string, name: string): Promise<{ error: string | null }>;
+  stopWorkspaceScript(workspaceId: string, name: string): Promise<{ error: string | null }>;
+  scheduleCreate?(options: Record<string, unknown>): Promise<{ schedule: { id: string } | null; error: string | null }>;
+  scheduleDelete?(options: { id: string }): Promise<{ error: string | null }>;
+  fetchWorkspaceSetupStatus?(
+    workspaceId: string,
+  ): Promise<{ snapshot: { status: "running" | "completed" | "failed" | "blocked"; error: string | null } | null }>;
+}

package/engine/src/paths.ts

@@ -0,0 +1,10 @@
+import path from "node:path";
+
+/** Compares directories the way the host filesystem does (case-insensitive on Windows and macOS). */
+export function samePath(a: string, b: string, platform: NodeJS.Platform = process.platform): boolean {
+  const norm = (p: string) => {
+    const resolved = (platform === "win32" ? path.win32 : path.posix).resolve(p).replace(/[\\/]+$/, "");
+    return platform === "win32" || platform === "darwin" ? resolved.toLowerCase() : resolved;
+  };
+  return norm(a) === norm(b);
+}