add-coder 0.3.26 → 0.3.28

package/templates/core/scripts/mcp-server/shared/hitl-proposal-mutation.ts

@@ -0,0 +1,98 @@
+import type { RuntimeContextKey } from "./runtime-context.js"
+import type { PlanLifecycleStatus } from "./plan-lifecycle.js"
+import {
+  createPlanLifecycleChangedEnvelope,
+  publishPlanLifecycleChanged,
+  type PrismaNotifyTransaction,
+} from "./plan-lifecycle-events.js"
+import type { HitlDecisionType } from "./hitl-lifecycle-mutation.js"
+
+export interface HitlProposalPlanRow {
+  id: string
+  projectKey: string
+  adapterKey: string
+  planName: string
+  lifecycle: PlanLifecycleStatus
+  revision: number
+}
+
+export interface HitlProposalRow {
+  id: string
+  projectKey: string
+  adapterKey: string
+  planName: string
+  round: number
+  type: HitlDecisionType
+  status: "DRAFT"
+}
+
+export interface HitlProposalTransaction extends PrismaNotifyTransaction {
+  planRecord: {
+    findFirst(args: { where: Record<string, unknown> }): Promise<HitlProposalPlanRow | null>
+    create(args: { data: Record<string, unknown> }): Promise<HitlProposalPlanRow>
+    update(args: { where: Record<string, unknown>; data: Record<string, unknown> }): Promise<HitlProposalPlanRow>
+  }
+  hitlRecord: {
+    findFirst(args: { where: Record<string, unknown>; orderBy: Record<string, unknown> }): Promise<HitlProposalRow | null>
+    create(args: { data: Record<string, unknown> }): Promise<HitlProposalRow>
+  }
+}
+
+export interface HitlProposalDatabase {
+  $transaction<T>(work: (tx: HitlProposalTransaction) => Promise<T>): Promise<T>
+}
+
+/** Advisory xact lock makes max(round)+1 atomic per scoped plan/type. */
+export async function createHitlProposalAndPublish(
+  database: HitlProposalDatabase,
+  input: {
+    context: RuntimeContextKey
+    planName: string
+    planPath: string
+    planKeyword: string
+    type: HitlDecisionType
+  },
+): Promise<{ planProvisioned: boolean; plan: HitlProposalPlanRow; hitl: HitlProposalRow }> {
+  return database.$transaction(async (tx) => {
+    const lockKey = `${input.context.contextId}:${input.planName}:${input.type}`
+    await tx.$executeRaw`SELECT pg_advisory_xact_lock(hashtext(${lockKey}))`
+    const scope = {
+      projectKey: input.context.projectKey,
+      adapterKey: input.context.adapterKey,
+      planName: input.planName,
+    }
+    const existing = await tx.planRecord.findFirst({ where: scope })
+    const plan = existing
+      ? await tx.planRecord.update({
+          where: { id: existing.id, revision: existing.revision },
+          data: { revision: { increment: 1 } },
+        })
+      : await tx.planRecord.create({
+          data: {
+            ...scope,
+            planPath: input.planPath,
+            planKeyword: input.planKeyword,
+            lifecycle: "DRAFT",
+            revision: 0,
+          },
+        })
+    const latest = await tx.hitlRecord.findFirst({
+      where: { ...scope, type: input.type },
+      orderBy: { round: "desc" },
+    })
+    const hitl = await tx.hitlRecord.create({
+      data: {
+        ...scope,
+        type: input.type,
+        round: (latest?.round ?? 0) + 1,
+        status: "DRAFT",
+      },
+    })
+    await publishPlanLifecycleChanged(tx, createPlanLifecycleChangedEnvelope({
+      context: input.context,
+      planId: plan.id,
+      revision: plan.revision,
+    }))
+    return { planProvisioned: existing === null, plan, hitl }
+  })
+}

package/templates/core/scripts/mcp-server/shared/hitl-ui.ts

@@ -0,0 +1,3 @@
+export const HITL_APPROVAL_WIDGET_URI = "ui://add-coder/hitl-approval"
+export const HITL_APPROVAL_WIDGET_MIME = "text/html;profile=mcp-app"
+export const HITL_APPROVAL_WIDGET_FILE = "hitl-approval-widget.html"

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})`
+}