@teamclaws/teamclaw 2026.3.26-2 → 2026.4.2-1

package/src/controller/controller-service.ts

@@ -1,46 +1,48 @@
 import type { OpenClawPluginApi, OpenClawPluginService, OpenClawPluginServiceContext, PluginLogger } from "../../api.js";
-import os from "node:os";
-import type { PluginConfig, TeamState } from "../types.js";
+import fs from "node:fs";
+import { exec } from "node:child_process";
+import type { KickoffAssessment, PluginConfig, RoleId, TeamState } from "../types.js";
 import { loadTeamState, saveTeamState } from "../state.js";
 import { MDnsAdvertiser } from "../discovery.js";
 import { WORKER_TIMEOUT_MS } from "../protocol.js";
 import { createControllerHttpServer } from "./http-server.js";
-import type { LocalWorkerManager } from "./local-worker-manager.js";
 import { TaskRouter } from "./task-router.js";
 import { MessageRouter } from "./message-router.js";
 import { TeamWebSocketServer } from "./websocket.js";
 import { ensureOpenClawWorkspaceMemoryDir } from "../openclaw-workspace.js";
 import { ensureControllerGitRepo } from "../git-collaboration.js";
 import { WorkerProvisioningManager } from "./worker-provisioning.js";
+import { PreviewManager } from "./preview-manager.js";
+import { runKickoffMeeting, buildKickoffAssessmentPrompt, ASSESSMENT_TIMEOUT_MS } from "./kickoff-orchestrator.js";
+import { resolvePreferredLanAddress } from "../networking.js";
+
+export type KickoffHandler = (
+  candidateRoles: RoleId[],
+  complexity: "simple" | "medium" | "complex",
+  requirement: string,
+) => Promise<{ assessments: KickoffAssessment[]; summary: string }>;
 
 export type ControllerServiceDeps = {
   config: PluginConfig;
   logger: PluginLogger;
   runtime: OpenClawPluginApi["runtime"];
-  localWorkerManager?: LocalWorkerManager;
   onTeamStateAvailable?: (getter: () => TeamState | null) => void;
+  /** Called once the HTTP server has bound to an actual port. */
+  onActualPort?: (port: number) => void;
+  /** Called once the kickoff handler is ready. */
+  onKickoffHandlerAvailable?: (handler: KickoffHandler) => void;
 };
 
 function getPreferredLanUiUrl(port: number): string | null {
-  const candidates: string[] = [];
-  const interfaces = os.networkInterfaces();
-  for (const records of Object.values(interfaces)) {
-    for (const record of records ?? []) {
-      if (!record || record.internal || record.family !== "IPv4") {
-        continue;
-      }
-      candidates.push(record.address);
-    }
-  }
-  candidates.sort((left, right) => left.localeCompare(right));
-  if (candidates.length === 0) {
+  const preferredLanAddress = resolvePreferredLanAddress();
+  if (!preferredLanAddress) {
     return null;
   }
-  return `http://${candidates[0]}:${port}/ui`;
+  return `http://${preferredLanAddress}:${port}/ui`;
 }
 
 export function createControllerService(deps: ControllerServiceDeps): OpenClawPluginService {
-  const { config, logger, localWorkerManager } = deps;
+  const { config, logger } = deps;
   let teamState: TeamState | null = null;
   let mdnsAdvertiser: MDnsAdvertiser;
   let taskRouter: TaskRouter;
@@ -48,6 +50,7 @@ export function createControllerService(deps: ControllerServiceDeps): OpenClawPl
   let wsServer: TeamWebSocketServer;
   let timeoutTimer: ReturnType<typeof setInterval> | null = null;
   let workerProvisioningManager: WorkerProvisioningManager | null = null;
+  let previewManager: PreviewManager;
 
   return {
     id: "teamclaw-controller",
@@ -95,24 +98,62 @@ export function createControllerService(deps: ControllerServiceDeps): OpenClawPl
         getTeamState: () => teamState,
         updateTeamState: updateState,
       });
+      if (workerProvisioningManager.isEnabled()) {
+        workerProvisioningManager.primeStartupReadiness();
+      }
+
+      previewManager = new PreviewManager({
+        logger,
+        getTeamState: () => teamState,
+        updateTeamState: updateState,
+      });
 
-      if (
-        repoStateChanged ||
-        localWorkerManager?.syncState(teamState) ||
-        workerProvisioningManager.syncState(teamState)
-      ) {
+      // Run ALL syncState calls (avoid || short-circuit skipping some).
+      const syncC = workerProvisioningManager.syncState(teamState);
+      if (repoStateChanged || syncC) {
         await saveTeamState(teamState);
       }
 
+      // Clean up orphaned tasks — tasks assigned to workers that no longer
+      // exist OR that are offline (stale entries surviving from a previous run).
+      {
+        let orphanCleaned = false;
+        for (const task of Object.values(teamState.tasks)) {
+          if (
+            task.assignedWorkerId &&
+            (task.status === "assigned" || task.status === "in_progress")
+          ) {
+            const worker = teamState.workers[task.assignedWorkerId];
+            if (!worker || worker.status === "offline") {
+              logger.info(`Controller: resetting orphaned task ${task.id} (worker ${task.assignedWorkerId} ${worker ? "offline" : "missing"})`);
+              task.status = "pending";
+              task.assignedWorkerId = undefined;
+              task.updatedAt = Date.now();
+              orphanCleaned = true;
+            }
+          }
+        }
+        if (orphanCleaned) {
+          await saveTeamState(teamState);
+        }
+      }
+
       mdnsAdvertiser = new MDnsAdvertiser(logger);
       taskRouter = new TaskRouter(logger);
       messageRouter = new MessageRouter(logger);
       wsServer = new TeamWebSocketServer(logger);
 
-      // Start mDNS advertising
-      await mdnsAdvertiser.start(config.port, config.teamName);
+      // When running inside a container (Docker or K8s), bind to 0.0.0.0
+      // so that port mapping, service networking, and health probes work.
+      // When running locally (host machine), bind to 127.0.0.1 for safety.
+      const isContainer = fs.existsSync("/.dockerenv") ||
+        fs.existsSync("/run/.containerenv") ||
+        process.env.KUBERNETES_SERVICE_HOST !== undefined;
+      const listenPort = config.port;
+      const listenHost = isContainer ? "0.0.0.0" : "127.0.0.1";
+
+      let serviceKickoffHandler: KickoffHandler | undefined;
 
-      // Start HTTP server
       const server = createControllerHttpServer({
         config,
         logger,
@@ -122,31 +163,90 @@ export function createControllerService(deps: ControllerServiceDeps): OpenClawPl
         taskRouter,
         messageRouter,
         wsServer,
-        localWorkerManager,
         workerProvisioningManager,
+        previewManager,
+        getKickoffHandler: () => serviceKickoffHandler,
       });
 
+      const PORT_RETRY_STEP = 10;
+      const PORT_MAX_RETRIES = 10;
+
+      let actualPort = 0;
       await new Promise<void>((resolve, reject) => {
-        server.listen(config.port, () => {
-          logger.info(`Controller: HTTP server listening on port ${config.port}`);
-          logger.info(`Controller: Web UI available at http://127.0.0.1:${config.port}/ui`);
-          const lanUiUrl = getPreferredLanUiUrl(config.port);
-          if (lanUiUrl) {
-            logger.info(`Controller: Web UI available on LAN at ${lanUiUrl}`);
-          }
-          resolve();
-        });
-        server.on("error", reject);
+        let attempt = 0;
+        const tryListen = (port: number) => {
+          server.once("error", (err: NodeJS.ErrnoException) => {
+            if (err.code === "EADDRINUSE" && attempt < PORT_MAX_RETRIES) {
+              attempt++;
+              const nextPort = config.port + attempt * PORT_RETRY_STEP;
+              logger.warn(`Controller: port ${port} in use, retrying on ${nextPort}`);
+              tryListen(nextPort);
+            } else {
+              reject(err);
+            }
+          });
+          server.listen(port, listenHost, () => {
+            const addr = server.address();
+            actualPort = typeof addr === "object" && addr ? addr.port : 0;
+            if (actualPort !== config.port) {
+              logger.info(`Controller: configured port ${config.port} unavailable, bound to ${actualPort} instead`);
+            }
+            logger.info(`Controller: HTTP server listening on port ${actualPort}`);
+            const uiUrl = `http://127.0.0.1:${actualPort}/ui`;
+            logger.info(`Controller: Web UI available at ${uiUrl}`);
+            const lanUiUrl = getPreferredLanUiUrl(actualPort);
+            if (lanUiUrl) {
+              logger.info(`Controller: Web UI available on LAN at ${lanUiUrl}`);
+            }
+            deps.onActualPort?.(actualPort);
+            openBrowser(uiUrl, logger);
+            resolve();
+          });
+        };
+        tryListen(listenPort);
       });
 
-      if (localWorkerManager?.hasLocalWorkers()) {
-        await localWorkerManager.start();
+      // Propagate the actual port to worker provisioning (created earlier, before port was known)
+      if (workerProvisioningManager.isEnabled()) {
+        workerProvisioningManager.setActualPort(actualPort);
       }
 
+      // Start mDNS advertising with the actual port
+      await mdnsAdvertiser.start(actualPort, config.teamName);
+
       if (workerProvisioningManager.isEnabled()) {
-        void workerProvisioningManager.requestReconcile("controller startup");
+        void workerProvisioningManager.runStartupReadinessCheck();
       }
 
+      // ── Kickoff handler ───────────────────────────────────────────────
+      const kickoffHandler: KickoffHandler = async (candidateRoles, complexity, requirement) => {
+        const result = await runKickoffMeeting(
+          { requirement, candidateRoles, complexity },
+          {
+            logger,
+            getTeamState: () => teamState,
+            ensureRoleProvisioned: async (role) => {
+              if (workerProvisioningManager?.isEnabled()) {
+                await workerProvisioningManager.requestReconcile(`kickoff-provision-${role}`);
+              }
+            },
+            requestWorkerAssessment: async (worker, req) => {
+              return await requestKickoffAssessment(worker, req);
+            },
+          },
+        );
+        return { assessments: result.plan.assessments, summary: result.summary };
+      };
+      serviceKickoffHandler = kickoffHandler;
+      deps.onKickoffHandlerAvailable?.(kickoffHandler);
+
+      logger.info(`Controller: starting preview restoration...`);
+      void previewManager.restorePreviewsOnStartup().then(() => {
+        logger.info(`Controller: preview restoration completed`);
+      }).catch((err) => {
+        logger.warn(`Controller: failed to restore previews on startup: ${String(err)}`);
+      });
+
       // Start timeout monitoring
       timeoutTimer = setInterval(() => {
         if (!teamState) return;
@@ -156,10 +256,6 @@ export function createControllerService(deps: ControllerServiceDeps): OpenClawPl
 
         for (const [workerId, worker] of Object.entries(teamState.workers)) {
           if (worker.status === "offline") continue;
-          if (localWorkerManager?.isLocalWorker(worker)) {
-            worker.lastHeartbeat = now;
-            continue;
-          }
           if (now - worker.lastHeartbeat > WORKER_TIMEOUT_MS) {
             logger.info(`Controller: worker ${workerId} timed out`);
             const activeTaskId = worker.currentTaskId;
@@ -210,15 +306,65 @@ export function createControllerService(deps: ControllerServiceDeps): OpenClawPl
         clearInterval(timeoutTimer);
         timeoutTimer = null;
       }
-      if (localWorkerManager?.hasLocalWorkers()) {
-        await localWorkerManager.stop();
-      }
       if (workerProvisioningManager) {
         await workerProvisioningManager.stop();
       }
+      await previewManager.stopAll();
       wsServer.close();
       mdnsAdvertiser.stop();
       logger.info("Controller: stopped");
     },
   };
 }
+
+function openBrowser(url: string, logger: PluginLogger): void {
+  const cmd = process.platform === "darwin"
+    ? `open "${url}"`
+    : process.platform === "win32"
+      ? `start "" "${url}"`
+      : `xdg-open "${url}"`;
+  exec(cmd, (err) => {
+    if (err) {
+      logger.warn(`Controller: failed to open browser: ${err.message}`);
+    }
+  });
+}
+
+/**
+ * Request a kickoff assessment from a worker.
+ *
+ * Request kickoff assessment from a worker over HTTP.
+ */
+async function requestKickoffAssessment(
+  worker: import("../types.js").WorkerInfo,
+  requirement: string,
+): Promise<import("../types.js").KickoffAssessment> {
+  const role = worker.role;
+  const prompt = buildKickoffAssessmentPrompt(role, requirement);
+
+  // External worker — POST to kickoff assess endpoint
+  if (!worker.url) {
+    throw new Error(`Worker ${worker.id} has no URL for kickoff assessment`);
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), ASSESSMENT_TIMEOUT_MS);
+
+  try {
+    const res = await fetch(`${worker.url}/api/v1/kickoff/assess`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ requirement, role }),
+      signal: controller.signal,
+    });
+
+    if (!res.ok) {
+      throw new Error(`Worker ${worker.id} returned ${res.status} for kickoff assessment`);
+    }
+
+    const data = await res.json() as { assessment: import("../types.js").KickoffAssessment };
+    return data.assessment;
+  } finally {
+    clearTimeout(timeout);
+  }
+}

package/src/controller/controller-tools.ts

@@ -1,12 +1,15 @@
 import { Type } from "@sinclair/typebox";
 import type {
   ControllerOrchestrationManifest,
+  KickoffAssessment,
   PluginConfig,
+  RoleId,
   TaskInfo,
   TeamState,
 } from "../types.js";
 import { buildControllerNoWorkersMessage, hasOnDemandWorkerProvisioning, shouldBlockControllerWithoutWorkers } from "./controller-capacity.js";
 import {
+  normalizeClarificationQuestionSchemas,
   normalizeManifestCreatedTasks,
   normalizeManifestDeferredTasks,
   normalizeManifestRoleList,
@@ -24,6 +27,8 @@ export type ControllerToolsDeps = {
   controllerUrl: string;
   getTeamState: () => TeamState | null;
   sessionKey?: string | null;
+  /** Handler for kickoff meeting requests. Use a getter for late-binding (service may start after tool registration). */
+  getKickoffHandler?: () => ((candidateRoles: RoleId[], complexity: "simple" | "medium" | "complex", requirement: string) => Promise<{ assessments: KickoffAssessment[]; summary: string }>) | undefined;
 };
 
 const EXECUTION_READY_BLOCKERS: Array<{ pattern: RegExp; reason: string }> = [
@@ -34,6 +39,11 @@ const EXECUTION_READY_BLOCKERS: Array<{ pattern: RegExp; reason: string }> = [
   { pattern: /待.*完成|等待.*完成/u, reason: "it is described as work for a later phase" },
 ];
 
+const VALID_ROLE_IDS = new Set([
+  "pm", "architect", "developer", "qa", "release-engineer",
+  "infra-engineer", "devops", "security-engineer", "designer", "marketing",
+]);
+
 const ENGLISH_LATER_PHASE_CLAUSE_RE = /\b(?:after|once)\b(.+?)\b(complete|completed|ready|available|exists?)\b/i;
 const ENGLISH_LATER_PHASE_DEPENDENCY_RE = /\b(?:task|tasks|service|services|module|modules|phase|phases|api|apis|interface|interfaces|review|qa|design|developer|architect|skeleton|backend|frontend|deliverable|artifact|handoff)\b/i;
 const CHINESE_LATER_PHASE_CLAUSE_RE = /(.+?)(完成后|就绪后)/u;
@@ -49,6 +59,68 @@ export function createControllerTools(deps: ControllerToolsDeps) {
   const baseUrl = controllerUrl;
 
   return [
+    {
+      name: "teamclaw_request_kickoff",
+      label: "Request Team Kickoff Meeting",
+      description: "Provision candidate role workers and collect structured assessments from each before creating execution tasks. Use for medium/complex projects where multiple roles need to collaborate.",
+      parameters: Type.Object({
+        requirement: Type.String({ description: "The full user requirement to present to the team for assessment" }),
+        candidateRoles: Type.Array(
+          Type.String({ description: "Role IDs to invite to the kickoff meeting (e.g. architect, developer, qa)" }),
+        ),
+        complexity: Type.Union([
+          Type.Literal("simple"),
+          Type.Literal("medium"),
+          Type.Literal("complex"),
+        ], { description: "Project complexity: simple (skip kickoff, 1-2 roles), medium (partial kickoff, 2-3 roles), complex (full team kickoff, 4+ roles)" }),
+      }),
+      async execute(_id: string, params: Record<string, unknown>) {
+        const kickoffHandler = deps.getKickoffHandler?.();
+        if (!kickoffHandler) {
+          return {
+            content: [{
+              type: "text" as const,
+              text: "Kickoff meeting is not available in this deployment. Proceed with direct task creation.",
+            }],
+          };
+        }
+
+        const requirement = String(params.requirement ?? "").trim();
+        if (!requirement) {
+          return { content: [{ type: "text" as const, text: "requirement is required." }] };
+        }
+
+        const rawRoles = Array.isArray(params.candidateRoles) ? params.candidateRoles : [];
+        const candidateRoles = rawRoles
+          .map((r) => String(r ?? "").trim().toLowerCase())
+          .filter((r): r is RoleId => VALID_ROLE_IDS.has(r));
+
+        if (candidateRoles.length === 0) {
+          return { content: [{ type: "text" as const, text: "At least one valid candidate role is required." }] };
+        }
+
+        const complexity = (params.complexity === "simple" || params.complexity === "medium" || params.complexity === "complex")
+          ? params.complexity
+          : "medium";
+
+        try {
+          const result = await kickoffHandler(candidateRoles, complexity, requirement);
+          return {
+            content: [{
+              type: "text" as const,
+              text: result.summary,
+            }],
+          };
+        } catch (err) {
+          return {
+            content: [{
+              type: "text" as const,
+              text: `Kickoff meeting failed: ${err instanceof Error ? err.message : String(err)}. Proceed with controller-only planning.`,
+            }],
+          };
+        }
+      },
+    },
     {
       name: "teamclaw_create_task",
       label: "Create Team Task",
@@ -152,6 +224,7 @@ export function createControllerTools(deps: ControllerToolsDeps) {
       label: "Submit Controller Manifest",
       description: "Record the structured orchestration manifest for this intake run after role selection and task creation decisions are complete",
       parameters: Type.Object({
+        projectName: Type.Optional(Type.String({ description: "Short, lowercase, kebab-case project name for the workspace directory (e.g. 'todo-rest-api', 'stripe-payment-integration'). 2-5 words max, no random suffixes." })),
         requirementSummary: Type.String({ description: "Brief summary of the requirement the controller is orchestrating" }),
         requiredRoles: Type.Array(
           Type.String({
@@ -162,6 +235,27 @@ export function createControllerTools(deps: ControllerToolsDeps) {
         clarificationQuestions: Type.Optional(
           Type.Array(Type.String({ description: "Concrete clarification questions still waiting on the human" })),
         ),
+        clarificationSchemas: Type.Optional(
+          Type.Array(
+            Type.Object({
+              kind: Type.String({ description: "Question kind: single-select, multi-select, number, or text" }),
+              title: Type.String({ description: "Question title shown to the human" }),
+              description: Type.Optional(Type.String({ description: "Optional supporting context for the question" })),
+              required: Type.Optional(Type.Boolean({ description: "Whether the human must answer this question before continuing" })),
+              options: Type.Optional(Type.Array(Type.Object({
+                value: Type.String({ description: "Stable option value" }),
+                label: Type.String({ description: "Human-visible option label" }),
+                hint: Type.Optional(Type.String({ description: "Optional helper text for this option" })),
+              }))),
+              allowOther: Type.Optional(Type.Boolean({ description: "Whether freeform 'other' text is allowed alongside options" })),
+              placeholder: Type.Optional(Type.String({ description: "Optional placeholder or hint for text/number input" })),
+              unit: Type.Optional(Type.String({ description: "Optional unit label for number questions" })),
+              min: Type.Optional(Type.Number({ description: "Optional minimum numeric value" })),
+              max: Type.Optional(Type.Number({ description: "Optional maximum numeric value" })),
+              step: Type.Optional(Type.Number({ description: "Optional numeric step size" })),
+            }),
+          ),
+        ),
         createdTasks: Type.Optional(
           Type.Array(
                 Type.Object({
@@ -183,6 +277,7 @@ export function createControllerTools(deps: ControllerToolsDeps) {
         ),
         handoffPlan: Type.Optional(Type.String({ description: "Brief note about how workers should report progress/handoffs across this flow" })),
         notes: Type.Optional(Type.String({ description: "Additional orchestration notes for the human/controller log" })),
+        requirementFullyComplete: Type.Optional(Type.Boolean({ description: "Set to true when the entire human requirement is fully satisfied — all tasks completed, no deferred tasks remaining, no follow-ups needed" })),
       }),
       async execute(_id: string, params: Record<string, unknown>) {
         const normalizedSessionKey = typeof sessionKey === "string" ? sessionKey.trim() : "";
@@ -200,16 +295,21 @@ export function createControllerTools(deps: ControllerToolsDeps) {
           return { content: [{ type: "text" as const, text: "requirementSummary is required." }] };
         }
 
+        const clarificationSchemas = normalizeClarificationQuestionSchemas(params.clarificationSchemas);
+        const clarificationQuestions = normalizeManifestStringList(params.clarificationQuestions);
         const manifest: ControllerOrchestrationManifest = {
           version: "1.0",
+          projectName: normalizeOptionalManifestText(params.projectName) || undefined,
           requirementSummary,
           requiredRoles: normalizeManifestRoleList(params.requiredRoles),
           clarificationsNeeded: Boolean(params.clarificationsNeeded),
-          clarificationQuestions: normalizeManifestStringList(params.clarificationQuestions),
+          clarificationQuestions: clarificationQuestions.length > 0 ? clarificationQuestions : clarificationSchemas.map((entry) => entry.title),
+          clarificationSchemas,
           createdTasks: normalizeManifestCreatedTasks(params.createdTasks),
           deferredTasks: normalizeManifestDeferredTasks(params.deferredTasks),
           handoffPlan: normalizeOptionalManifestText(params.handoffPlan),
           notes: normalizeOptionalManifestText(params.notes),
+          requirementFullyComplete: Boolean(params.requirementFullyComplete),
         };
 
         try {
@@ -230,7 +330,7 @@ export function createControllerTools(deps: ControllerToolsDeps) {
           return {
             content: [{
               type: "text" as const,
-              text: `Controller manifest recorded: roles=${manifest.requiredRoles.join(", ") || "none"} created=${manifest.createdTasks.length} deferred=${manifest.deferredTasks.length}`,
+              text: `Controller manifest recorded: roles=${manifest.requiredRoles.join(", ") || "none"} created=${manifest.createdTasks.length} deferred=${manifest.deferredTasks.length}${manifest.requirementFullyComplete ? " requirementFullyComplete=true" : ""}`,
             }],
           };
         } catch (err) {