add-coder 0.3.25 → 0.3.27

package/templates/core/scripts/mcp-server/shared/plan-lifecycle-events.ts

@@ -0,0 +1,62 @@
+import { randomUUID } from "crypto"
+import * as z from "zod/v4"
+import type { RuntimeContextKey } from "./runtime-context.js"
+
+export const PLAN_LIFECYCLE_CHANNEL = "add_plan_lifecycle_changed_v1"
+
+export const PlanLifecycleChangedEnvelopeSchema = z.object({
+  schemaVersion: z.literal(1),
+  eventId: z.string().min(1),
+  projectKey: z.string().min(1),
+  adapterKey: z.string().min(1),
+  planId: z.string().min(1),
+  revision: z.number().int().nonnegative(),
+})
+
+export type PlanLifecycleChangedEnvelope = z.infer<typeof PlanLifecycleChangedEnvelopeSchema>
+
+export interface PrismaNotifyTransaction {
+  $executeRaw(query: TemplateStringsArray, ...values: unknown[]): Promise<number>
+}
+
+export function createPlanLifecycleChangedEnvelope(input: {
+  context: RuntimeContextKey
+  planId: string
+  revision: number
+  eventId?: string
+}): PlanLifecycleChangedEnvelope {
+  return {
+    schemaVersion: 1,
+    eventId: input.eventId ?? randomUUID(),
+    projectKey: input.context.projectKey,
+    adapterKey: input.context.adapterKey,
+    planId: input.planId,
+    revision: input.revision,
+  }
+}
+
+export function parsePlanLifecycleChangedEnvelope(payload: string | undefined): PlanLifecycleChangedEnvelope | null {
+  if (!payload) return null
+  try {
+    const parsed: unknown = JSON.parse(payload)
+    const result = PlanLifecycleChangedEnvelopeSchema.safeParse(parsed)
+    return result.success ? result.data : null
+  } catch {
+    return null
+  }
+}
+
+export function isLifecycleEventForContext(
+  envelope: PlanLifecycleChangedEnvelope,
+  context: RuntimeContextKey,
+): boolean {
+  return envelope.projectKey === context.projectKey && envelope.adapterKey === context.adapterKey
+}
+
+export async function publishPlanLifecycleChanged(
+  tx: PrismaNotifyTransaction,
+  envelope: PlanLifecycleChangedEnvelope,
+): Promise<void> {
+  const payload = JSON.stringify(envelope)
+  await tx.$executeRaw`SELECT pg_notify(${PLAN_LIFECYCLE_CHANNEL}, ${payload})`
+}

package/templates/core/scripts/mcp-server/shared/plan-lifecycle-mutation.ts

@@ -0,0 +1,78 @@
+import type { RuntimeContextKey } from "./runtime-context.js"
+import { assertLifecycleTransition, type PlanLifecycleStatus } from "./plan-lifecycle.js"
+import {
+  createPlanLifecycleChangedEnvelope,
+  publishPlanLifecycleChanged,
+  type PrismaNotifyTransaction,
+} from "./plan-lifecycle-events.js"
+
+export interface PlanLifecycleMutationRow {
+  id: string
+  projectKey: string
+  adapterKey: string
+  planName: string
+  lifecycle: PlanLifecycleStatus
+  revision: number
+}
+
+export interface PlanLifecycleTransaction extends PrismaNotifyTransaction {
+  planRecord: {
+    findFirst(args: { where: Record<string, unknown> }): Promise<PlanLifecycleMutationRow | null>
+    update(args: {
+      where: Record<string, unknown>
+      data: { lifecycle: PlanLifecycleStatus; revision: { increment: 1 } }
+    }): Promise<PlanLifecycleMutationRow>
+  }
+}
+
+export interface PlanLifecycleDatabase {
+  $transaction<T>(work: (tx: PlanLifecycleTransaction) => Promise<T>): Promise<T>
+}
+
+export interface TransitionPlanLifecycleInput {
+  context: RuntimeContextKey
+  planName: string
+  to: PlanLifecycleStatus
+  expectedRevision?: number
+}
+
+export async function transitionPlanLifecycle(
+  database: PlanLifecycleDatabase,
+  input: TransitionPlanLifecycleInput,
+): Promise<PlanLifecycleMutationRow> {
+  return database.$transaction(async (tx) => {
+    const current = await tx.planRecord.findFirst({
+      where: {
+        projectKey: input.context.projectKey,
+        adapterKey: input.context.adapterKey,
+        planName: input.planName,
+      },
+    })
+    if (!current) {
+      throw new Error(`当前 RuntimeContextKey 下不存在 Plan: ${input.planName}`)
+    }
+    if (current.projectKey !== input.context.projectKey || current.adapterKey !== input.context.adapterKey) {
+      throw new Error("拒绝迁移 scope 外 Plan lifecycle")
+    }
+    if (input.expectedRevision !== undefined && current.revision !== input.expectedRevision) {
+      throw new Error(`Plan lifecycle revision 冲突: expected=${input.expectedRevision}, actual=${current.revision}`)
+    }
+    assertLifecycleTransition(current.lifecycle, input.to)
+    if (current.lifecycle === input.to) return current
+
+    const updated = await tx.planRecord.update({
+      where: { id: current.id, revision: current.revision },
+      data: { lifecycle: input.to, revision: { increment: 1 } },
+    })
+    if (updated.revision !== current.revision + 1) {
+      throw new Error(`Plan lifecycle revision 未按预期递增: ${current.revision} → ${updated.revision}`)
+    }
+    const envelope = createPlanLifecycleChangedEnvelope({
+      context: input.context,
+      planId: updated.id,
+      revision: updated.revision,
+    })
+    await publishPlanLifecycleChanged(tx, envelope)
+    return updated
+  })
+}

package/templates/core/scripts/mcp-server/shared/plan-lifecycle-subscriber.ts

@@ -0,0 +1,145 @@
+import type { RuntimeContextKey } from "./runtime-context.js"
+import type { PlanStatusResolution } from "./plan-lifecycle.js"
+import {
+  isLifecycleEventForContext,
+  parsePlanLifecycleChangedEnvelope,
+  PLAN_LIFECYCLE_CHANNEL,
+  type PlanLifecycleChangedEnvelope,
+} from "./plan-lifecycle-events.js"
+
+export interface PgNotification {
+  channel: string
+  payload?: string
+}
+
+export interface LifecycleListenClient {
+  connect(): Promise<unknown>
+  query(sql: string): Promise<unknown>
+  end(): Promise<void>
+  on(event: "notification", listener: (message: PgNotification) => void): this
+  on(event: "error", listener: (error: Error) => void): this
+  on(event: "end", listener: () => void): this
+  removeAllListeners(): this
+}
+
+export type LifecycleListenClientFactory = () => LifecycleListenClient | Promise<LifecycleListenClient>
+
+export interface PlanLifecycleSubscriberOptions {
+  context: RuntimeContextKey
+  clientFactory: LifecycleListenClientFactory
+  resolveStatus(input: {
+    context: RuntimeContextKey
+    planId?: string
+    reason: "initial" | "notification" | "reconnect"
+  }): Promise<PlanStatusResolution>
+  onSnapshot(snapshot: PlanStatusResolution, envelope?: PlanLifecycleChangedEnvelope): void | Promise<void>
+  onError?(error: Error): void
+  reconnectDelayMs?: number
+}
+
+export class PlanLifecycleSubscriber {
+  readonly #options: PlanLifecycleSubscriberOptions
+  #client: LifecycleListenClient | null = null
+  #stopping = false
+  #startedOnce = false
+  #reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  #refreshQueue: Promise<void> = Promise.resolve()
+
+  constructor(options: PlanLifecycleSubscriberOptions) {
+    this.#options = options
+  }
+
+  async start(): Promise<void> {
+    if (this.#client) return
+    this.#stopping = false
+    try {
+      await this.#connectAndHydrate("initial")
+    } catch (error) {
+      this.#scheduleReconnect()
+      throw error
+    }
+  }
+
+  async stop(): Promise<void> {
+    this.#stopping = true
+    if (this.#reconnectTimer) clearTimeout(this.#reconnectTimer)
+    this.#reconnectTimer = null
+    const client = this.#client
+    this.#client = null
+    if (!client) return
+    client.removeAllListeners()
+    try { await client.query(`UNLISTEN ${PLAN_LIFECYCLE_CHANNEL}`) } catch { /* connection may already be gone */ }
+    await client.end().catch(() => undefined)
+    await this.#refreshQueue
+  }
+
+  async #connectAndHydrate(reason: "initial" | "reconnect"): Promise<void> {
+    const client = await this.#options.clientFactory()
+    this.#client = client
+    client.on("notification", (message) => this.#handleNotification(message))
+    client.on("error", (error) => this.#handleDisconnect(client, error))
+    client.on("end", () => this.#handleDisconnect(client, new Error("PostgreSQL LISTEN session ended")))
+    try {
+      await client.connect()
+      await client.query(`LISTEN ${PLAN_LIFECYCLE_CHANNEL}`)
+      await this.#refresh(undefined, reason)
+      this.#startedOnce = true
+    } catch (error) {
+      if (this.#client === client) this.#client = null
+      client.removeAllListeners()
+      await client.end().catch(() => undefined)
+      const normalized = error instanceof Error ? error : new Error(String(error))
+      this.#options.onError?.(normalized)
+      throw normalized
+    }
+  }
+
+  #handleNotification(message: PgNotification): void {
+    if (this.#stopping || message.channel !== PLAN_LIFECYCLE_CHANNEL) return
+    const envelope = parsePlanLifecycleChangedEnvelope(message.payload)
+    if (!envelope || !isLifecycleEventForContext(envelope, this.#options.context)) return
+    this.#refreshQueue = this.#refreshQueue
+      .then(() => this.#refresh(envelope, "notification"))
+      .catch((error: unknown) => this.#options.onError?.(error instanceof Error ? error : new Error(String(error))))
+  }
+
+  #handleDisconnect(client: LifecycleListenClient, error: Error): void {
+    if (this.#stopping || this.#client !== client) return
+    this.#client = null
+    client.removeAllListeners()
+    this.#options.onError?.(error)
+    if (this.#reconnectTimer) return
+    this.#reconnectTimer = setTimeout(() => {
+      this.#reconnectTimer = null
+      if (this.#stopping) return
+      this.#connectAndHydrate(this.#startedOnce ? "reconnect" : "initial")
+        .catch(() => this.#scheduleReconnect())
+    }, this.#options.reconnectDelayMs ?? 1000)
+  }
+
+  #scheduleReconnect(): void {
+    if (this.#stopping || this.#reconnectTimer) return
+    this.#reconnectTimer = setTimeout(() => {
+      this.#reconnectTimer = null
+      this.#connectAndHydrate(this.#startedOnce ? "reconnect" : "initial")
+        .catch(() => this.#scheduleReconnect())
+    }, this.#options.reconnectDelayMs ?? 1000)
+  }
+
+  async #refresh(
+    envelope: PlanLifecycleChangedEnvelope | undefined,
+    reason: "initial" | "notification" | "reconnect",
+  ): Promise<void> {
+    const snapshot = await this.#options.resolveStatus({
+      context: this.#options.context,
+      planId: envelope?.planId,
+      reason,
+    })
+    await this.#options.onSnapshot(snapshot, envelope)
+  }
+}
+
+export async function createPgLifecycleListenClient(databaseUrl: string): Promise<LifecycleListenClient> {
+  const { Client } = await import("pg")
+  return new Client({ connectionString: databaseUrl })
+}

package/templates/core/scripts/mcp-server/shared/plan-lifecycle.ts

@@ -0,0 +1,153 @@
+import type { RuntimeContextKey } from "./runtime-context.js"
+
+export const PLAN_LIFECYCLE_STATUSES = [
+  "DRAFT",
+  "ACTIVE",
+  "BLOCKED",
+  "REJECTED",
+  "CLOSED",
+  "ABANDONED",
+] as const
+
+export type PlanLifecycleStatus = (typeof PLAN_LIFECYCLE_STATUSES)[number]
+export type PlanApprovalStatus = "DRAFT" | "SUBMITTED" | "TONGYI" | "BOHUI"
+
+export interface ScopedPlanStatusRow {
+  id: string
+  projectKey: string
+  adapterKey: string
+  planName: string
+  lifecycle: PlanLifecycleStatus
+  revision: number
+  doneTasks: number
+  totalTasks: number
+  checklistTDone: number
+  checklistT: number
+}
+
+export interface PlanStatusStore {
+  findPlan(input: {
+    context: RuntimeContextKey
+    planName?: string
+    planId?: string
+    activeOnly?: boolean
+  }): Promise<ScopedPlanStatusRow | null>
+  findLatestPlanApproval(input: {
+    context: RuntimeContextKey
+    planName: string
+  }): Promise<PlanApprovalStatus | null>
+}
+
+export interface PlanStatusSnapshot {
+  availability: "READY"
+  source: "database"
+  context: Pick<RuntimeContextKey, "projectKey" | "adapterKey" | "contextId">
+  planName: string
+  planId: string
+  lifecycle: PlanLifecycleStatus
+  revision: number
+  isActive: boolean
+  approvalStatus: PlanApprovalStatus | null
+  progress: {
+    doneTasks: number
+    totalTasks: number
+    checklistTDone: number
+    checklistT: number
+  }
+}
+
+export interface NoActivePlanSnapshot {
+  availability: "READY"
+  source: "database"
+  context: Pick<RuntimeContextKey, "projectKey" | "adapterKey" | "contextId">
+  planName: null
+  lifecycle: null
+  isActive: false
+}
+
+export interface PlanStatusUnavailable {
+  availability: "STATUS_UNAVAILABLE"
+  source: "database"
+  context: Pick<RuntimeContextKey, "projectKey" | "adapterKey" | "contextId">
+  reason: string
+}
+
+export type PlanStatusResolution = PlanStatusSnapshot | NoActivePlanSnapshot | PlanStatusUnavailable
+
+const ALLOWED_TRANSITIONS: Readonly<Record<PlanLifecycleStatus, readonly PlanLifecycleStatus[]>> = {
+  DRAFT: ["ACTIVE", "REJECTED", "ABANDONED"],
+  ACTIVE: ["BLOCKED", "CLOSED", "ABANDONED"],
+  BLOCKED: ["ACTIVE", "CLOSED", "ABANDONED"],
+  REJECTED: ["DRAFT", "ACTIVE", "ABANDONED"],
+  CLOSED: [],
+  ABANDONED: [],
+}
+
+export function isActiveLifecycle(lifecycle: PlanLifecycleStatus): boolean {
+  return lifecycle === "ACTIVE" || lifecycle === "BLOCKED"
+}
+
+export function assertLifecycleTransition(from: PlanLifecycleStatus, to: PlanLifecycleStatus): void {
+  if (from === to) return
+  if (!ALLOWED_TRANSITIONS[from].includes(to)) {
+    throw new Error(`非法 Plan lifecycle 迁移: ${from} → ${to}`)
+  }
+}
+
+function snapshotContext(context: RuntimeContextKey) {
+  return { projectKey: context.projectKey, adapterKey: context.adapterKey, contextId: context.contextId }
+}
+
+export async function resolvePlanStatus(
+  store: PlanStatusStore,
+  context: RuntimeContextKey,
+  selector?: string | { planName?: string; planId?: string; activeOnly?: boolean },
+): Promise<PlanStatusResolution> {
+  try {
+    const selection = typeof selector === "string" ? { planName: selector } : (selector ?? {})
+    const plan = await store.findPlan({
+      context,
+      planName: selection.planName,
+      planId: selection.planId,
+      activeOnly: selection.activeOnly ?? (selection.planName === undefined && selection.planId === undefined),
+    })
+    if (!plan) {
+      return {
+        availability: "READY",
+        source: "database",
+        context: snapshotContext(context),
+        planName: null,
+        lifecycle: null,
+        isActive: false,
+      }
+    }
+    if (plan.projectKey !== context.projectKey || plan.adapterKey !== context.adapterKey) {
+      throw new Error("PlanStatusStore 返回了 scope 外记录")
+    }
+    const approvalStatus = await store.findLatestPlanApproval({ context, planName: plan.planName })
+    return {
+      availability: "READY",
+      source: "database",
+      context: snapshotContext(context),
+      planName: plan.planName,
+      planId: plan.id,
+      lifecycle: plan.lifecycle,
+      revision: plan.revision,
+      isActive: isActiveLifecycle(plan.lifecycle),
+      approvalStatus,
+      progress: {
+        doneTasks: plan.doneTasks,
+        totalTasks: plan.totalTasks,
+        checklistTDone: plan.checklistTDone,
+        checklistT: plan.checklistT,
+      },
+    }
+  } catch (error) {
+    return {
+      availability: "STATUS_UNAVAILABLE",
+      source: "database",
+      context: snapshotContext(context),
+      reason: error instanceof Error ? error.message : String(error),
+    }
+  }
+}

package/templates/core/scripts/mcp-server/shared/plan-round-events.ts

@@ -0,0 +1,56 @@
+import { randomUUID } from "crypto"
+import * as z from "zod/v4"
+import type { RuntimeContextKey } from "./runtime-context.js"
+import type { PrismaNotifyTransaction } from "./plan-lifecycle-events.js"
+
+export const PLAN_ROUND_CHANNEL = "add_plan_round_changed_v1"
+
+export const PlanRoundChangedEnvelopeSchema = z.object({
+  schemaVersion: z.literal(1),
+  eventId: z.string().min(1),
+  projectKey: z.string().min(1),
+  adapterKey: z.string().min(1),
+  planId: z.string().min(1),
+})
+
+export type PlanRoundChangedEnvelope = z.infer<typeof PlanRoundChangedEnvelopeSchema>
+
+export function createPlanRoundChangedEnvelope(input: {
+  context: RuntimeContextKey
+  planId: string
+  eventId?: string
+}): PlanRoundChangedEnvelope {
+  return {
+    schemaVersion: 1,
+    eventId: input.eventId ?? randomUUID(),
+    projectKey: input.context.projectKey,
+    adapterKey: input.context.adapterKey,
+    planId: input.planId,
+  }
+}
+
+export function parsePlanRoundChangedEnvelope(payload: string | undefined): PlanRoundChangedEnvelope | null {
+  if (!payload) return null
+  try {
+    const parsed: unknown = JSON.parse(payload)
+    const result = PlanRoundChangedEnvelopeSchema.safeParse(parsed)
+    return result.success ? result.data : null
+  } catch {
+    return null
+  }
+}
+
+export function isPlanRoundEventForContext(
+  envelope: PlanRoundChangedEnvelope,
+  context: RuntimeContextKey,
+): boolean {
+  return envelope.projectKey === context.projectKey && envelope.adapterKey === context.adapterKey
+}
+
+export async function publishPlanRoundChanged(
+  tx: PrismaNotifyTransaction,
+  envelope: PlanRoundChangedEnvelope,
+): Promise<void> {
+  const payload = JSON.stringify(envelope)
+  await tx.$executeRaw`SELECT pg_notify(${PLAN_ROUND_CHANNEL}, ${payload})`
+}

package/templates/core/scripts/mcp-server/shared/plan-round-mutation.ts

@@ -0,0 +1,143 @@
+import { createHash } from "crypto"
+import type { RuntimeContextKey } from "./runtime-context.js"
+import {
+  createPlanRoundChangedEnvelope,
+  publishPlanRoundChanged,
+} from "./plan-round-events.js"
+import type { PrismaNotifyTransaction } from "./plan-lifecycle-events.js"
+
+export interface PlanRoundPlanRow {
+  id: string
+  projectKey: string
+  adapterKey: string
+  planName: string
+  lifecycle: string
+  revision: number
+}
+
+export interface PlanRoundOperationRow {
+  id: string
+  projectKey: string
+  producerAdapterKey: string
+  contextId: string
+  toolName: string
+  operationKey: string
+  planKeyword: string
+  action: string
+  targetType: string
+  targetId: string
+  beforeState: unknown
+  afterState: unknown
+  reason: string | null
+  createdAt: Date
+}
+
+export interface PlanRoundTransaction extends PrismaNotifyTransaction {
+  planRecord: {
+    findFirst(args: { where: Record<string, unknown> }): Promise<PlanRoundPlanRow | null>
+  }
+  addUser: {
+    findUnique(args: { where: Record<string, unknown>; select: Record<string, unknown> }): Promise<{ id: string } | null>
+    create(args: { data: Record<string, unknown> }): Promise<{ id: string }>
+  }
+  devOperation: {
+    upsert(args: { where: Record<string, unknown>; create: Record<string, unknown>; update: Record<string, unknown> }): Promise<PlanRoundOperationRow>
+  }
+}
+
+export interface PlanRoundDatabase {
+  $transaction<T>(work: (tx: PlanRoundTransaction) => Promise<T>): Promise<T>
+}
+
+export interface ClosePlanRoundInput {
+  context: RuntimeContextKey
+  planName: string
+  round: number
+  beforeState: Record<string, unknown> | unknown[]
+  afterState: Record<string, unknown> | unknown[]
+  reason?: string
+  operationKey?: string
+}
+
+export interface ClosePlanRoundResult {
+  plan: PlanRoundPlanRow
+  operation: PlanRoundOperationRow
+}
+
+export function defaultPlanRoundOperationKey(input: {
+  context: RuntimeContextKey
+  planId: string
+  round: number
+}): string {
+  return createHash("sha256")
+    .update(`${input.context.contextId}:${input.planId}:ROUND_CLOSED:${input.round}`)
+    .digest("hex")
+}
+
+export async function closePlanRoundAndPublish(
+  database: PlanRoundDatabase,
+  input: ClosePlanRoundInput,
+): Promise<ClosePlanRoundResult> {
+  if (!Number.isInteger(input.round) || input.round < 1) throw new Error("round 必须是大于 0 的整数")
+
+  return database.$transaction(async (tx) => {
+    const plan = await tx.planRecord.findFirst({
+      where: {
+        projectKey: input.context.projectKey,
+        adapterKey: input.context.adapterKey,
+        planName: input.planName,
+      },
+    })
+    if (!plan) throw new Error(`当前 RuntimeContextKey 下不存在 Plan: ${input.planName}`)
+    if (plan.projectKey !== input.context.projectKey || plan.adapterKey !== input.context.adapterKey) {
+      throw new Error("拒绝关闭 scope 外 PlanRound")
+    }
+
+    let user = await tx.addUser.findUnique({ where: { username: "ai-assistant" }, select: { id: true } })
+    if (!user) {
+      user = await tx.addUser.create({
+        data: { id: "ai-assistant", username: "ai-assistant", email: "ai-assistant@internal" },
+      })
+    }
+    const baseOperationKey = defaultPlanRoundOperationKey({
+      context: input.context,
+      planId: plan.id,
+      round: input.round,
+    })
+    const operationKey = input.operationKey?.trim()
+      ? createHash("sha256").update(`${baseOperationKey}:${input.operationKey.trim()}`).digest("hex")
+      : baseOperationKey
+    const operation = await tx.devOperation.upsert({
+      where: {
+        projectKey_producerAdapterKey_toolName_operationKey: {
+          projectKey: input.context.projectKey,
+          producerAdapterKey: input.context.adapterKey,
+          toolName: "plan_round_close",
+          operationKey,
+        },
+      },
+      create: {
+        userId: user.id,
+        projectKey: input.context.projectKey,
+        producerAdapterKey: input.context.adapterKey,
+        contextId: input.context.contextId,
+        toolName: "plan_round_close",
+        operationKey,
+        planKeyword: input.planName,
+        action: "ROUND_CLOSED",
+        targetType: "PLAN_ROUND",
+        targetId: `${input.planName}::round${input.round}`,
+        beforeState: input.beforeState,
+        afterState: input.afterState,
+        reason: input.reason ?? null,
+      },
+      update: {},
+    })
+
+    await publishPlanRoundChanged(tx, createPlanRoundChangedEnvelope({
+      context: input.context,
+      planId: plan.id,
+    }))
+    return { plan, operation }
+  })
+}

package/templates/core/scripts/mcp-server/shared/plan-round-store.ts

@@ -0,0 +1,47 @@
+import type { RuntimeContextKey } from "./runtime-context.js"
+import type { PlanRoundOperationRow } from "./plan-round-mutation.js"
+
+export interface PlanRoundReadClient {
+  planRecord: {
+    findFirst(args: { where: Record<string, unknown>; orderBy: Record<string, unknown> }): Promise<{ id: string; planName: string } | null>
+  }
+  devOperation: {
+    findMany(args: { where: Record<string, unknown>; orderBy: Record<string, unknown> }): Promise<PlanRoundOperationRow[]>
+  }
+}
+
+export interface PlanRoundSnapshot {
+  context: RuntimeContextKey
+  planId: string | null
+  planName: string | null
+  rounds: PlanRoundOperationRow[]
+}
+
+export async function queryPlanRounds(
+  client: PlanRoundReadClient,
+  input: { context: RuntimeContextKey; planName?: string; planId?: string; round?: number },
+): Promise<PlanRoundSnapshot> {
+  const explicitPlan = Boolean(input.planName || input.planId)
+  const plan = await client.planRecord.findFirst({
+    where: {
+      projectKey: input.context.projectKey,
+      adapterKey: input.context.adapterKey,
+      ...(input.planName ? { planName: input.planName } : {}),
+      ...(input.planId ? { id: input.planId } : {}),
+      ...(!explicitPlan ? { lifecycle: { in: ["ACTIVE", "BLOCKED"] } } : {}),
+    },
+    orderBy: { updatedAt: "desc" },
+  })
+  if (!plan) return { context: input.context, planId: null, planName: null, rounds: [] }
+
+  const where: Record<string, unknown> = {
+    projectKey: input.context.projectKey,
+    producerAdapterKey: input.context.adapterKey,
+    toolName: "plan_round_close",
+    action: "ROUND_CLOSED",
+    planKeyword: plan.planName,
+  }
+  if (input.round !== undefined) where.targetId = `${plan.planName}::round${input.round}`
+  const rounds = await client.devOperation.findMany({ where, orderBy: { createdAt: "asc" } })
+  return { context: input.context, planId: plan.id, planName: plan.planName, rounds }
+}