@chllming/wave-orchestration 0.7.0 → 0.7.2

package/scripts/wave-orchestrator/human-input-workflow.mjs

@@ -0,0 +1,289 @@
+import { toIsoTimestamp } from "./shared.mjs";
+
+// ── Human Input Workflow State Machine ──
+//
+// States: open -> pending -> answered -> resolved
+//                         -> escalated -> resolved
+
+export const HUMAN_INPUT_STATES = new Set([
+  "open",
+  "pending",
+  "answered",
+  "escalated",
+  "resolved",
+]);
+
+export const HUMAN_INPUT_VALID_TRANSITIONS = {
+  open: ["pending", "escalated", "resolved"],
+  pending: ["answered", "escalated", "resolved"],
+  answered: ["resolved"],
+  escalated: ["answered", "resolved"],
+  resolved: [],
+};
+
+const BLOCKING_STATES = new Set(["open", "pending", "escalated"]);
+
+const DEFAULT_TIMEOUT_POLICY = {
+  maxWaitMs: 300000,
+  escalateAfterMs: 120000,
+};
+
+const DEFAULT_REROUTE_POLICY = {
+  rerouteOnTimeout: true,
+  rerouteTo: "operator",
+};
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function normalizeText(value, fallback = null) {
+  const normalized = String(value ?? "").trim();
+  return normalized || fallback;
+}
+
+export function normalizeHumanInputRequest(request, defaults = {}) {
+  const source = isPlainObject(request) ? request : {};
+  const defaultSource = isPlainObject(defaults) ? defaults : {};
+  const now = toIsoTimestamp();
+
+  const timeoutPolicy = isPlainObject(source.timeoutPolicy)
+    ? {
+        maxWaitMs: Number.isFinite(source.timeoutPolicy.maxWaitMs)
+          ? source.timeoutPolicy.maxWaitMs
+          : DEFAULT_TIMEOUT_POLICY.maxWaitMs,
+        escalateAfterMs: Number.isFinite(source.timeoutPolicy.escalateAfterMs)
+          ? source.timeoutPolicy.escalateAfterMs
+          : DEFAULT_TIMEOUT_POLICY.escalateAfterMs,
+      }
+    : { ...DEFAULT_TIMEOUT_POLICY };
+
+  const reroutePolicy = isPlainObject(source.reroutePolicy)
+    ? {
+        rerouteOnTimeout: source.reroutePolicy.rerouteOnTimeout !== false,
+        rerouteTo: normalizeText(source.reroutePolicy.rerouteTo, DEFAULT_REROUTE_POLICY.rerouteTo),
+      }
+    : { ...DEFAULT_REROUTE_POLICY };
+
+  const rawState = normalizeText(source.state, normalizeText(defaultSource.state, "open"));
+  const state = HUMAN_INPUT_STATES.has(rawState) ? rawState : "open";
+
+  return {
+    requestId: normalizeText(source.requestId, normalizeText(defaultSource.requestId, null)),
+    kind: normalizeText(source.kind, normalizeText(defaultSource.kind, "human-input")),
+    state,
+    title: normalizeText(source.title, normalizeText(defaultSource.title, null)),
+    detail: normalizeText(source.detail, normalizeText(defaultSource.detail, null)),
+    requestedBy: normalizeText(source.requestedBy, normalizeText(defaultSource.requestedBy, null)),
+    assignedTo: normalizeText(source.assignedTo, normalizeText(defaultSource.assignedTo, null)),
+    timeoutPolicy,
+    reroutePolicy,
+    createdAt: normalizeText(source.createdAt, normalizeText(defaultSource.createdAt, now)),
+    updatedAt: normalizeText(source.updatedAt, normalizeText(defaultSource.updatedAt, now)),
+    answeredAt: normalizeText(source.answeredAt, null),
+    resolvedAt: normalizeText(source.resolvedAt, null),
+    escalatedAt: normalizeText(source.escalatedAt, null),
+    answer: normalizeText(source.answer, null),
+    resolution: normalizeText(source.resolution, null),
+  };
+}
+
+export function transitionHumanInputState(currentState, targetState) {
+  if (!HUMAN_INPUT_STATES.has(currentState)) {
+    throw new Error(`Invalid current state: ${currentState}`);
+  }
+  if (!HUMAN_INPUT_STATES.has(targetState)) {
+    throw new Error(`Invalid target state: ${targetState}`);
+  }
+  const allowed = HUMAN_INPUT_VALID_TRANSITIONS[currentState];
+  if (!allowed || !allowed.includes(targetState)) {
+    throw new Error(
+      `Invalid transition from "${currentState}" to "${targetState}". Allowed: [${(allowed || []).join(", ")}]`,
+    );
+  }
+  return targetState;
+}
+
+export function isHumanInputBlocking(request) {
+  const source = isPlainObject(request) ? request : {};
+  const state = normalizeText(source.state, "open");
+  return BLOCKING_STATES.has(state);
+}
+
+export function buildHumanInputRequests(coordinationState, feedbackRequests, options = {}) {
+  const results = [];
+  const coordState = isPlainObject(coordinationState) ? coordinationState : {};
+  const feedbackList = Array.isArray(feedbackRequests) ? feedbackRequests : [];
+  const now = toIsoTimestamp();
+
+  // Process clarification-request records from coordination state
+  const clarifications = Array.isArray(coordState.clarifications)
+    ? coordState.clarifications
+    : [];
+  for (const record of clarifications) {
+    if (!isPlainObject(record)) continue;
+    const kind = normalizeText(record.kind, null);
+    if (
+      kind !== "clarification-request" &&
+      kind !== "human-escalation" &&
+      kind !== "human-feedback"
+    ) {
+      continue;
+    }
+    const mappedKind =
+      kind === "clarification-request"
+        ? "clarification"
+        : kind === "human-escalation"
+          ? "escalation"
+          : "feedback";
+    const rawStatus = normalizeText(record.status, "open");
+    let mappedState = "open";
+    if (rawStatus === "in_progress" || rawStatus === "pending") {
+      mappedState = "pending";
+    } else if (rawStatus === "resolved" || rawStatus === "closed") {
+      mappedState = "resolved";
+    } else if (rawStatus === "answered") {
+      mappedState = "answered";
+    }
+    results.push(
+      normalizeHumanInputRequest({
+        requestId: normalizeText(record.id, null),
+        kind: mappedKind,
+        state: mappedState,
+        title: normalizeText(record.summary, null),
+        detail: normalizeText(record.detail, null),
+        requestedBy: normalizeText(record.agentId, null),
+        assignedTo: null,
+        createdAt: normalizeText(record.createdAt, now),
+        updatedAt: normalizeText(record.updatedAt, now),
+      }),
+    );
+  }
+
+  // Process human escalations from coordination state
+  const humanEscalations = Array.isArray(coordState.humanEscalations)
+    ? coordState.humanEscalations
+    : [];
+  for (const record of humanEscalations) {
+    if (!isPlainObject(record)) continue;
+    const rawStatus = normalizeText(record.status, "open");
+    let mappedState = "escalated";
+    if (rawStatus === "resolved" || rawStatus === "closed") {
+      mappedState = "resolved";
+    } else if (rawStatus === "answered") {
+      mappedState = "answered";
+    }
+    results.push(
+      normalizeHumanInputRequest({
+        requestId: normalizeText(record.id, null),
+        kind: "escalation",
+        state: mappedState,
+        title: normalizeText(record.summary, null),
+        detail: normalizeText(record.detail, null),
+        requestedBy: normalizeText(record.agentId, null),
+        assignedTo: "operator",
+        createdAt: normalizeText(record.createdAt, now),
+        updatedAt: normalizeText(record.updatedAt, now),
+        escalatedAt: normalizeText(record.createdAt, now),
+      }),
+    );
+  }
+
+  // Process feedback requests
+  for (const record of feedbackList) {
+    if (!isPlainObject(record)) continue;
+    const rawStatus = normalizeText(record.status, "pending");
+    let mappedState = "pending";
+    if (rawStatus === "answered") {
+      mappedState = "answered";
+    } else if (rawStatus === "resolved" || rawStatus === "closed") {
+      mappedState = "resolved";
+    }
+    results.push(
+      normalizeHumanInputRequest({
+        requestId: normalizeText(record.id, null),
+        kind: "feedback",
+        state: mappedState,
+        title: normalizeText(record.question, null),
+        detail: normalizeText(record.context, null),
+        requestedBy: normalizeText(record.agentId, null),
+        assignedTo: "operator",
+        createdAt: normalizeText(record.createdAt, now),
+        updatedAt: normalizeText(record.updatedAt, now),
+        answeredAt: normalizeText(record.response?.answeredAt, null),
+        answer: normalizeText(record.response?.text, null),
+      }),
+    );
+  }
+
+  return results;
+}
+
+export function evaluateHumanInputTimeout(request, now = Date.now()) {
+  const source = isPlainObject(request) ? request : {};
+  const createdAtMs = Date.parse(source.createdAt || "");
+  if (!Number.isFinite(createdAtMs)) {
+    return { expired: false, shouldEscalate: false, elapsedMs: 0 };
+  }
+  const elapsedMs = Math.max(0, now - createdAtMs);
+  const policy = isPlainObject(source.timeoutPolicy)
+    ? source.timeoutPolicy
+    : DEFAULT_TIMEOUT_POLICY;
+  const maxWaitMs = Number.isFinite(policy.maxWaitMs)
+    ? policy.maxWaitMs
+    : DEFAULT_TIMEOUT_POLICY.maxWaitMs;
+  const escalateAfterMs = Number.isFinite(policy.escalateAfterMs)
+    ? policy.escalateAfterMs
+    : DEFAULT_TIMEOUT_POLICY.escalateAfterMs;
+  const expired = elapsedMs >= maxWaitMs;
+  const shouldEscalate = elapsedMs >= escalateAfterMs;
+  return { expired, shouldEscalate, elapsedMs };
+}
+
+export function computeHumanInputMetrics(requests) {
+  const list = Array.isArray(requests) ? requests : [];
+  const counts = { open: 0, pending: 0, answered: 0, escalated: 0, resolved: 0 };
+  let blocking = 0;
+  let overdueCount = 0;
+  let totalResolutionMs = 0;
+  let resolvedWithTimesCount = 0;
+
+  for (const request of list) {
+    const source = isPlainObject(request) ? request : {};
+    const state = normalizeText(source.state, "open");
+    if (state in counts) {
+      counts[state] += 1;
+    }
+    if (BLOCKING_STATES.has(state)) {
+      blocking += 1;
+    }
+    // Check overdue based on timeout policy
+    const timeout = evaluateHumanInputTimeout(source);
+    if (timeout.expired && BLOCKING_STATES.has(state)) {
+      overdueCount += 1;
+    }
+    // Compute resolution time for resolved requests
+    if (state === "resolved" && source.createdAt && source.resolvedAt) {
+      const createdMs = Date.parse(source.createdAt);
+      const resolvedMs = Date.parse(source.resolvedAt);
+      if (Number.isFinite(createdMs) && Number.isFinite(resolvedMs) && resolvedMs >= createdMs) {
+        totalResolutionMs += resolvedMs - createdMs;
+        resolvedWithTimesCount += 1;
+      }
+    }
+  }
+
+  return {
+    total: list.length,
+    open: counts.open,
+    pending: counts.pending,
+    answered: counts.answered,
+    escalated: counts.escalated,
+    resolved: counts.resolved,
+    blocking,
+    overdueCount,
+    avgResolutionMs: resolvedWithTimesCount > 0
+      ? Math.round(totalResolutionMs / resolvedWithTimesCount)
+      : null,
+  };
+}

package/scripts/wave-orchestrator/install.mjs

@@ -92,6 +92,33 @@ const REQUIRED_GITIGNORE_ENTRIES = [
   "docs/research/papers/",
   "docs/research/articles/",
 ];
+const PLANNER_MIGRATION_REQUIRED_SURFACES = [
+  {
+    id: "planner-role",
+    label: "docs/agents/wave-planner-role.md",
+    path: "docs/agents/wave-planner-role.md",
+    kind: "file",
+  },
+  {
+    id: "planner-skill",
+    label: "skills/role-planner/",
+    path: "skills/role-planner",
+    kind: "dir",
+  },
+  {
+    id: "planner-context7",
+    label: "docs/context7/planner-agent/",
+    path: "docs/context7/planner-agent",
+    kind: "dir",
+  },
+  {
+    id: "planner-lessons",
+    label: "docs/reference/wave-planning-lessons.md",
+    path: "docs/reference/wave-planning-lessons.md",
+    kind: "file",
+  },
+];
+const PLANNER_REQUIRED_BUNDLE_ID = "planner-agentic";
 
 function collectDeclaredDeployKinds(waves = []) {
   return Array.from(
@@ -171,6 +198,28 @@ function copyTemplateFile(relPath) {
     throw new Error(`Missing packaged template: ${relPath}`);
   }
   ensureDirectory(path.dirname(targetPath));
+  if (relPath === "docs/plans/component-cutover-matrix.json") {
+    const payload = readJsonOrNull(sourcePath);
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+      throw new Error(`Invalid packaged template JSON: ${relPath}`);
+    }
+    const components = Object.fromEntries(
+      Object.entries(payload.components || {}).map(([componentId, component]) => [
+        componentId,
+        {
+          ...component,
+          promotions: Array.isArray(component?.promotions)
+            ? component.promotions.filter((entry) => Number(entry?.wave) === 0)
+            : [],
+        },
+      ]),
+    );
+    writeJsonAtomic(targetPath, {
+      ...payload,
+      components,
+    });
+    return targetPath;
+  }
   fs.copyFileSync(sourcePath, targetPath);
   return targetPath;
 }
@@ -222,6 +271,8 @@ function slugifyVersion(value) {
 }
 
 function formatUpgradeReport(report) {
+  const plannerMigrationErrors = report.doctor.errors.filter((issue) => isPlannerMigrationIssue(issue));
+  const otherDoctorErrors = report.doctor.errors.filter((issue) => !isPlannerMigrationIssue(issue));
   return [
     `# Wave Upgrade Report`,
     "",
@@ -238,12 +289,27 @@ function formatUpgradeReport(report) {
     "",
     "- No repo-owned plans, waves, role prompts, or config files were overwritten.",
     "- New runtime behavior comes from the installed package version.",
+    ...(report.initMode === "adopt-existing" && plannerMigrationErrors.length > 0
+      ? [
+          "",
+          "## Adopted Repo Follow-Up",
+          "",
+          "- This workspace was adopted from an existing repo-owned Wave surface.",
+          "- `wave upgrade` does not copy new planner starter docs, skills, or Context7 bundle entries into adopted repos.",
+          ...plannerMigrationErrors.map((issue) => `- Error: ${issue}`),
+        ]
+      : []),
+    ...(report.initMode === "adopt-existing" && plannerMigrationErrors.length > 0
+      ? [
+          "- After syncing that planner surface, rerun `pnpm exec wave doctor` before relying on `wave draft --agentic` or planner-aware validation.",
+        ]
+      : []),
     ...(report.doctor.errors.length > 0 || report.doctor.warnings.length > 0
       ? [
           "",
           "## Follow-Up",
           "",
-          ...report.doctor.errors.map((issue) => `- Error: ${issue}`),
+          ...otherDoctorErrors.map((issue) => `- Error: ${issue}`),
           ...report.doctor.warnings.map((issue) => `- Warning: ${issue}`),
         ]
       : []),
@@ -275,6 +341,48 @@ function plannerRequiredPaths() {
   ).sort();
 }
 
+function isPlannerMigrationIssue(issue) {
+  return String(issue || "").startsWith("Planner starter surface is incomplete");
+}
+
+function missingPlannerMigrationSurfaceLabels() {
+  const missing = [];
+  for (const surface of PLANNER_MIGRATION_REQUIRED_SURFACES) {
+    const targetPath = path.join(REPO_ROOT, surface.path);
+    if (!fs.existsSync(targetPath)) {
+      missing.push(surface.label);
+      continue;
+    }
+    if (surface.kind === "dir") {
+      try {
+        if (fs.readdirSync(targetPath).length === 0) {
+          missing.push(surface.label);
+        }
+      } catch {
+        missing.push(surface.label);
+      }
+    }
+  }
+  return missing;
+}
+
+function plannerMigrationIssue(config, context7BundleIndex) {
+  const missing = missingPlannerMigrationSurfaceLabels();
+  const bundleId = String(config?.planner?.agentic?.context7Bundle || "").trim();
+  const bundleEntryMissing =
+    bundleId === "" || bundleId === PLANNER_REQUIRED_BUNDLE_ID
+      ? !context7BundleIndex?.bundles?.[PLANNER_REQUIRED_BUNDLE_ID]
+      : false;
+  if (missing.length === 0 && !bundleEntryMissing) {
+    return null;
+  }
+  const remediationItems = missing.slice();
+  if (bundleEntryMissing) {
+    remediationItems.push(`docs/context7/bundles.json#${PLANNER_REQUIRED_BUNDLE_ID}`);
+  }
+  return `Planner starter surface is incomplete for 0.7.x workspaces. Sync ${remediationItems.join(", ")} from the packaged release, then rerun \`pnpm exec wave doctor\`.`;
+}
+
 export function runDoctor() {
   const errors = [];
   const warnings = [];
@@ -320,14 +428,22 @@ export function runDoctor() {
         }
       }
       const context7BundleIndex = loadContext7BundleIndex(lanePaths.context7BundleIndexPath);
+      const plannerMigration = plannerMigrationIssue(config, context7BundleIndex);
+      if (plannerMigration) {
+        errors.push(plannerMigration);
+      }
       const plannerPaths = plannerRequiredPaths();
       for (const relPath of plannerPaths) {
-        if (!fs.existsSync(path.join(REPO_ROOT, relPath))) {
+        if (!fs.existsSync(path.join(REPO_ROOT, relPath)) && !plannerMigration) {
           errors.push(`Missing planner file: ${relPath}`);
         }
       }
       const plannerBundleId = String(config.planner?.agentic?.context7Bundle || "").trim();
-      if (plannerBundleId && !context7BundleIndex.bundles[plannerBundleId]) {
+      if (
+        plannerBundleId &&
+        !context7BundleIndex.bundles[plannerBundleId] &&
+        !(plannerMigration && plannerBundleId === PLANNER_REQUIRED_BUNDLE_ID)
+      ) {
         errors.push(
           `planner.agentic.context7Bundle references unknown bundle "${plannerBundleId}".`,
         );
@@ -484,6 +600,7 @@ export function upgradeWorkspace() {
     previousVersion,
     currentVersion: metadata.version,
     generatedAt,
+    initMode: existingState.initMode || null,
     releases,
     doctor,
   };