@teamclaws/teamclaw 2026.3.21 → 2026.3.25

package/src/controller/http-server.ts

@@ -5,6 +5,8 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import type { OpenClawPluginApi, PluginLogger } from "../../api.js";
 import type {
   ClarificationRequest,
+  ControllerRunInfo,
+  ControllerRunSource,
   GitRepoState,
   PluginConfig,
   RepoSyncInfo,
@@ -29,7 +31,7 @@ import {
   generateId,
 } from "../protocol.js";
 import { listWorkspaceTree, readWorkspaceFile, readWorkspaceRawFile } from "../workspace-browser.js";
-import { ROLES } from "../roles.js";
+import { ROLES, normalizeRecommendedSkills, resolveRecommendedSkillsForRole } from "../roles.js";
 import { buildRepoSyncInfo, ensureControllerGitRepo, exportControllerGitBundle, importControllerGitBundle } from "../git-collaboration.js";
 import type { LocalWorkerManager } from "./local-worker-manager.js";
 import { TaskRouter } from "./task-router.js";
@@ -51,6 +53,7 @@ export type ControllerHttpDeps = {
 };
 
 const MAX_TASK_EXECUTION_EVENTS = 250;
+const MAX_CONTROLLER_RUNS = 40;
 const MAX_RECENT_TASK_CONTEXT = 3;
 const MAX_TASK_CONTEXT_SUMMARY_CHARS = 500;
 const CONTROLLER_INTAKE_TIMEOUT_CAP_MS = 180_000;
@@ -167,6 +170,196 @@ function buildTaskExecutionSummary(execution?: TaskExecution): TaskExecutionSumm
   };
 }
 
+function ensureControllerRunExecution(run: ControllerRunInfo): TaskExecution {
+  if (!run.execution) {
+    run.execution = {
+      status: run.status,
+      runId: run.runId,
+      startedAt: run.startedAt,
+      endedAt: run.completedAt,
+      lastUpdatedAt: run.updatedAt,
+      events: [],
+    };
+  }
+
+  if (!Array.isArray(run.execution.events)) {
+    run.execution.events = [];
+  }
+
+  run.execution.status = run.status;
+  run.execution.runId = run.runId ?? run.execution.runId;
+  run.execution.startedAt = run.startedAt ?? run.execution.startedAt;
+  run.execution.endedAt = run.completedAt ?? run.execution.endedAt;
+  run.execution.lastUpdatedAt = run.updatedAt ?? run.execution.lastUpdatedAt;
+  return run.execution;
+}
+
+function appendControllerRunEvent(run: ControllerRunInfo, input: TaskExecutionEventInput): TaskExecutionEvent {
+  const now = input.createdAt ?? Date.now();
+  const execution = ensureControllerRunExecution(run);
+
+  if (input.runId) {
+    run.runId = input.runId;
+    execution.runId = input.runId;
+  }
+  if (input.sessionKey) {
+    execution.sessionKey = input.sessionKey;
+  }
+  if (input.status) {
+    run.status = input.status;
+    execution.status = input.status;
+  }
+
+  if ((input.status === "running" || input.phase === "run_started") && !run.startedAt) {
+    run.startedAt = now;
+    execution.startedAt = now;
+  }
+  if (run.status === "completed" || run.status === "failed") {
+    run.completedAt = run.completedAt ?? now;
+    execution.endedAt = execution.endedAt ?? now;
+  }
+
+  run.updatedAt = now;
+  execution.lastUpdatedAt = now;
+
+  const event: TaskExecutionEvent = {
+    id: generateId(),
+    type: input.type,
+    createdAt: now,
+    message: input.message,
+    phase: input.phase,
+    source: input.source,
+    stream: input.stream,
+  };
+
+  execution.events.push(event);
+  if (execution.events.length > MAX_TASK_EXECUTION_EVENTS) {
+    execution.events = execution.events.slice(-MAX_TASK_EXECUTION_EVENTS);
+  }
+
+  return event;
+}
+
+function trimControllerRuns(state: TeamState): void {
+  const runs = Object.values(state.controllerRuns)
+    .sort((left, right) => left.updatedAt - right.updatedAt);
+  if (runs.length <= MAX_CONTROLLER_RUNS) {
+    return;
+  }
+  for (const run of runs.slice(0, runs.length - MAX_CONTROLLER_RUNS)) {
+    delete state.controllerRuns[run.id];
+  }
+}
+
+function serializeControllerRun(run?: ControllerRunInfo, includeExecutionEvents = true): Record<string, unknown> | undefined {
+  if (!run) {
+    return undefined;
+  }
+
+  const payload: Record<string, unknown> = { ...run };
+  if (!run.execution) {
+    return payload;
+  }
+
+  payload.execution = includeExecutionEvents
+    ? {
+        status: run.execution.status,
+        runId: run.execution.runId,
+        startedAt: run.execution.startedAt,
+        endedAt: run.execution.endedAt,
+        lastUpdatedAt: run.execution.lastUpdatedAt,
+        events: run.execution.events.map((event) => ({ ...event })),
+      }
+    : buildTaskExecutionSummary(run.execution);
+
+  return payload;
+}
+
+function buildControllerRunTitle(
+  message: string,
+  source: ControllerRunSource,
+  sourceTaskTitle?: string,
+): string {
+  if (source === "task_follow_up") {
+    return sourceTaskTitle
+      ? `Controller follow-up after ${sourceTaskTitle}`
+      : "Controller workflow follow-up";
+  }
+
+  const normalized = message.replace(/\s+/g, " ").trim();
+  if (!normalized) {
+    return "Controller intake";
+  }
+  if (normalized.length <= 100) {
+    return normalized;
+  }
+  return `${normalized.slice(0, 100).trimEnd()}…`;
+}
+
+function createControllerRun(
+  message: string,
+  sessionKey: string,
+  deps: ControllerHttpDeps,
+  options?: {
+    source?: ControllerRunSource;
+    sourceTaskId?: string;
+    sourceTaskTitle?: string;
+  },
+): ControllerRunInfo {
+  const now = Date.now();
+  const run: ControllerRunInfo = {
+    id: generateId(),
+    title: buildControllerRunTitle(message, options?.source ?? "human", options?.sourceTaskTitle),
+    sessionKey,
+    source: options?.source ?? "human",
+    sourceTaskId: options?.sourceTaskId,
+    sourceTaskTitle: options?.sourceTaskTitle,
+    request: message,
+    createdTaskIds: [],
+    status: "pending",
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  const state = deps.updateTeamState((teamState) => {
+    teamState.controllerRuns[run.id] = run;
+    trimControllerRuns(teamState);
+  });
+  const createdRun = state.controllerRuns[run.id] ?? run;
+  deps.wsServer.broadcastUpdate({ type: "controller:run", data: serializeControllerRun(createdRun) });
+  return createdRun;
+}
+
+function updateControllerRun(
+  runId: string,
+  deps: ControllerHttpDeps,
+  updater: (run: ControllerRunInfo) => void,
+): ControllerRunInfo | undefined {
+  const state = deps.updateTeamState((teamState) => {
+    const run = teamState.controllerRuns[runId];
+    if (!run) {
+      return;
+    }
+    updater(run);
+    trimControllerRuns(teamState);
+  });
+  const updatedRun = state.controllerRuns[runId];
+  if (updatedRun) {
+    deps.wsServer.broadcastUpdate({ type: "controller:run", data: serializeControllerRun(updatedRun) });
+  }
+  return updatedRun;
+}
+
+function recordControllerRunEvent(
+  runId: string,
+  input: TaskExecutionEventInput,
+  deps: ControllerHttpDeps,
+): ControllerRunInfo | undefined {
+  return updateControllerRun(runId, deps, (run) => {
+    appendControllerRunEvent(run, input);
+  });
+}
+
 function serializeTask(task?: TaskInfo, includeExecutionEvents = false): Record<string, unknown> | undefined {
   if (!task) {
     return undefined;
@@ -248,7 +441,8 @@ function tagControllerCreatedTasks(
   taskIdsBeforeRun: Set<string>,
   sessionKey: string,
   deps: ControllerHttpDeps,
-): void {
+): string[] {
+  const taggedTaskIds: string[] = [];
   deps.updateTeamState((state) => {
     for (const task of Object.values(state.tasks)) {
       if (taskIdsBeforeRun.has(task.id)) {
@@ -258,8 +452,10 @@ function tagControllerCreatedTasks(
         continue;
       }
       task.controllerSessionKey = sessionKey;
+      taggedTaskIds.push(task.id);
     }
   });
+  return taggedTaskIds;
 }
 
 function buildControllerFollowUpMessage(task: TaskInfo): string {
@@ -297,20 +493,48 @@ async function continueControllerWorkflow(task: TaskInfo, deps: ControllerHttpDe
   if (task.createdBy !== "controller" || !task.controllerSessionKey) {
     return;
   }
-  await runControllerIntake(buildControllerFollowUpMessage(task), task.controllerSessionKey, deps);
+  await runControllerIntake(buildControllerFollowUpMessage(task), task.controllerSessionKey, deps, {
+    source: "task_follow_up",
+    sourceTaskId: task.id,
+    sourceTaskTitle: task.title,
+  });
 }
 
 async function runControllerIntake(
   message: string,
   sessionKey: string,
   deps: ControllerHttpDeps,
-): Promise<{ sessionKey: string; runId: string; reply: string }> {
+  options?: {
+    source?: ControllerRunSource;
+    sourceTaskId?: string;
+    sourceTaskTitle?: string;
+  },
+): Promise<{ sessionKey: string; runId: string; reply: string; controllerRunId: string }> {
   const taskIdsBeforeRun = collectTaskIds(deps.getTeamState());
+  const controllerRun = createControllerRun(message, sessionKey, deps, options);
+  recordControllerRunEvent(controllerRun.id, {
+    type: "lifecycle",
+    phase: "queued",
+    source: "controller",
+    status: "pending",
+    sessionKey,
+    message: "Controller intake queued.",
+  }, deps);
+
   const runResult = await deps.runtime.subagent.run({
     sessionKey,
     message,
     idempotencyKey: `controller-intake-${generateId()}`,
   });
+  recordControllerRunEvent(controllerRun.id, {
+    type: "lifecycle",
+    phase: "run_started",
+    source: "controller",
+    status: "running",
+    sessionKey,
+    runId: runResult.runId,
+    message: `Controller intake started (${runResult.runId}).`,
+  }, deps);
 
   const waitResult = await deps.runtime.subagent.waitForRun({
     runId: runResult.runId,
@@ -318,26 +542,90 @@ async function runControllerIntake(
   });
 
   if (waitResult.status === "timeout") {
-    tagControllerCreatedTasks(taskIdsBeforeRun, sessionKey, deps);
+    const createdTaskIds = tagControllerCreatedTasks(taskIdsBeforeRun, sessionKey, deps);
+    updateControllerRun(controllerRun.id, deps, (run) => {
+      run.createdTaskIds = createdTaskIds;
+      run.error = "Controller intake timed out";
+      appendControllerRunEvent(run, {
+        type: "error",
+        phase: "timeout",
+        source: "controller",
+        status: "failed",
+        sessionKey,
+        runId: runResult.runId,
+        message: "Controller intake timed out.",
+      });
+    });
     throw new Error("Controller intake timed out");
   }
   if (waitResult.status !== "ok") {
-    tagControllerCreatedTasks(taskIdsBeforeRun, sessionKey, deps);
-    throw new Error(waitResult.error || "Controller intake failed");
+    const errorMessage = waitResult.error || "Controller intake failed";
+    const createdTaskIds = tagControllerCreatedTasks(taskIdsBeforeRun, sessionKey, deps);
+    updateControllerRun(controllerRun.id, deps, (run) => {
+      run.createdTaskIds = createdTaskIds;
+      run.error = errorMessage;
+      appendControllerRunEvent(run, {
+        type: "error",
+        phase: "run_failed",
+        source: "controller",
+        status: "failed",
+        sessionKey,
+        runId: runResult.runId,
+        message: errorMessage,
+      });
+    });
+    throw new Error(errorMessage);
   }
 
-  tagControllerCreatedTasks(taskIdsBeforeRun, sessionKey, deps);
+  const createdTaskIds = tagControllerCreatedTasks(taskIdsBeforeRun, sessionKey, deps);
 
   const sessionMessages = await deps.runtime.subagent.getSessionMessages({
     sessionKey,
     limit: 100,
   });
-  const reply = extractLastAssistantText(sessionMessages.messages);
+  const reply = extractLastAssistantText(sessionMessages.messages)
+    || "Controller completed the intake run but did not return any text.";
+
+  updateControllerRun(controllerRun.id, deps, (run) => {
+    run.reply = reply;
+    run.error = undefined;
+    run.createdTaskIds = createdTaskIds;
+    appendControllerRunEvent(run, {
+      type: "output",
+      phase: "final_reply",
+      source: "subagent",
+      status: "running",
+      sessionKey,
+      runId: runResult.runId,
+      message: reply,
+    });
+    if (createdTaskIds.length > 0) {
+      appendControllerRunEvent(run, {
+        type: "lifecycle",
+        phase: "tasks_created",
+        source: "controller",
+        status: "running",
+        sessionKey,
+        runId: runResult.runId,
+        message: `Controller created ${createdTaskIds.length} task(s): ${createdTaskIds.join(", ")}`,
+      });
+    }
+    appendControllerRunEvent(run, {
+      type: "lifecycle",
+      phase: "run_completed",
+      source: "controller",
+      status: "completed",
+      sessionKey,
+      runId: runResult.runId,
+      message: "Controller intake completed.",
+    });
+  });
 
   return {
     sessionKey,
     runId: runResult.runId,
-    reply: reply || "Controller completed the intake run but did not return any text.",
+    reply,
+    controllerRunId: controllerRun.id,
   };
 }
 
@@ -384,8 +672,27 @@ function buildRecentCompletedTaskContext(task: TaskInfo, state: TeamState | null
   ].join("\n");
 }
 
+function buildRecommendedSkillsContext(task: TaskInfo): string {
+  const recommendedSkills = resolveRecommendedSkillsForRole(task.assignedRole, task.recommendedSkills ?? []);
+  if (recommendedSkills.length === 0) {
+    return "";
+  }
+
+  return [
+    "## Recommended Skills",
+    "- Prefer these skill slugs for this task when relevant:",
+    ...recommendedSkills.map((skill) => `  - ${skill}`),
+    "- Before starting, search/install missing recommended skills in the current workspace when the runtime supports it.",
+    "- Prefer exact ClawHub/OpenClaw skill slugs over vague descriptions whenever possible.",
+  ].join("\n");
+}
+
 function buildTaskAssignmentDescription(task: TaskInfo, state: TeamState | null, repoInfo?: RepoSyncInfo): string {
   const parts = [task.description];
+  const recommendedSkillsContext = buildRecommendedSkillsContext(task);
+  if (recommendedSkillsContext) {
+    parts.push("", recommendedSkillsContext);
+  }
   const recentContext = buildRecentCompletedTaskContext(task, state);
   if (recentContext) {
     parts.push("", recentContext);
@@ -746,11 +1053,13 @@ async function dispatchTaskToWorker(
   const repoState = await refreshControllerRepoState(deps);
   const repoInfo = buildRepoSyncInfo(repoState, sharedWorkspace);
   const description = buildTaskAssignmentDescription(task, state ?? null, repoInfo);
+  const recommendedSkills = resolveRecommendedSkillsForRole(task.assignedRole, task.recommendedSkills ?? []);
   const assignment: TaskAssignmentPayload = {
     taskId: task.id,
     title: task.title,
     description,
     priority: task.priority,
+    recommendedSkills,
     repo: repoInfo,
   };
 
@@ -1139,6 +1448,9 @@ async function handleRequest(
     const priority = typeof body.priority === "string" ? body.priority as TaskPriority : "medium";
     const assignedRole = typeof body.assignedRole === "string" ? body.assignedRole as RoleId : undefined;
     const createdBy = typeof body.createdBy === "string" ? body.createdBy : "boss";
+    const recommendedSkills = normalizeRecommendedSkills(
+      Array.isArray(body.recommendedSkills) ? body.recommendedSkills.map((entry) => String(entry ?? "")) : [],
+    );
 
     if (!title) {
       sendError(res, 400, "title is required");
@@ -1157,6 +1469,7 @@ async function handleRequest(
       priority,
       assignedRole,
       createdBy,
+      recommendedSkills: recommendedSkills.length > 0 ? recommendedSkills : undefined,
       createdAt: now,
       updatedAt: now,
     };
@@ -1184,6 +1497,16 @@ async function handleRequest(
         role: assignedRole,
       }, deps);
     }
+    if (recommendedSkills.length > 0) {
+      recordTaskExecutionEvent(taskId, {
+        type: "lifecycle",
+        phase: "skills_recommended",
+        source: "controller",
+        status: "pending",
+        message: `Recommended skills: ${recommendedSkills.join(", ")}`,
+        role: assignedRole,
+      }, deps);
+    }
 
     await autoAssignPendingTasks(deps);
 
@@ -1259,6 +1582,12 @@ async function handleRequest(
       if (typeof body.progress === "string") task.progress = body.progress as string;
       if (typeof body.priority === "string") task.priority = body.priority as TaskPriority;
       if (typeof body.assignedRole === "string") task.assignedRole = body.assignedRole as RoleId;
+      if (Array.isArray(body.recommendedSkills)) {
+        const recommendedSkills = normalizeRecommendedSkills(
+          body.recommendedSkills.map((entry: unknown) => String(entry ?? "")),
+        );
+        task.recommendedSkills = recommendedSkills.length > 0 ? recommendedSkills : undefined;
+      }
       task.updatedAt = Date.now();
 
       if (typeof body.status === "string" && body.status !== previousStatus) {
@@ -1463,6 +1792,18 @@ async function handleRequest(
 
   // ==================== Message Routing ====================
 
+  // GET /api/v1/controller/runs
+  if (req.method === "GET" && pathname === "/api/v1/controller/runs") {
+    const state = getTeamState();
+    const controllerRuns = state
+      ? Object.values(state.controllerRuns)
+        .sort((left, right) => right.updatedAt - left.updatedAt)
+        .map((run) => serializeControllerRun(run))
+      : [];
+    sendJson(res, 200, { controllerRuns });
+    return;
+  }
+
   // POST /api/v1/controller/intake
   if (req.method === "POST" && pathname === "/api/v1/controller/intake") {
     const body = await parseJsonBody(req);
@@ -1907,6 +2248,7 @@ async function handleRequest(
         teamName: config.teamName,
         workers: [],
         tasks: [],
+        controllerRuns: [],
         messages: [],
         clarifications: [],
         repo: null,
@@ -1920,6 +2262,9 @@ async function handleRequest(
       teamName: state.teamName,
       workers: Object.values(state.workers),
       tasks: Object.values(state.tasks).map((task) => serializeTask(task)),
+      controllerRuns: Object.values(state.controllerRuns)
+        .sort((left, right) => right.updatedAt - left.updatedAt)
+        .map((run) => serializeControllerRun(run)),
       messages: state.messages,
       clarifications,
       repo: state.repo ?? null,

package/src/controller/local-worker-manager.ts

@@ -1,5 +1,4 @@
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import net from "node:net";
 import { spawn, type ChildProcess } from "node:child_process";
@@ -19,6 +18,7 @@ import type {
 import {
   resolveDefaultOpenClawConfigPath,
   resolveDefaultOpenClawStateDir,
+  resolveDefaultTeamClawRuntimeRootDir,
   resolveDefaultOpenClawWorkspaceDir,
 } from "../openclaw-workspace.js";
 
@@ -125,8 +125,10 @@ export class LocalWorkerManager {
     }
 
     this.stoppingAll = false;
+    const workerBaseRoot = path.join(resolveDefaultTeamClawRuntimeRootDir(), "local-workers");
+    await fs.mkdir(workerBaseRoot, { recursive: true });
     this.workerBaseDir = await fs.mkdtemp(
-      path.join(os.tmpdir(), `teamclaw-local-workers-${sanitizePathSegment(this.deps.config.teamName)}-`),
+      path.join(workerBaseRoot, `${sanitizePathSegment(this.deps.config.teamName)}-`),
     );
 
     const sourceStateDir = resolveDefaultOpenClawStateDir();
@@ -153,7 +155,7 @@ export class LocalWorkerManager {
 
     if (this.workerBaseDir) {
       await fs.rm(this.workerBaseDir, { recursive: true, force: true }).catch(() => {
-        // Best-effort cleanup; tmpdirs are safe to leave behind.
+        // Best-effort cleanup; managed runtime dirs are safe to leave behind.
       });
       this.workerBaseDir = null;
     }

package/src/controller/prompt-injector.ts

@@ -80,7 +80,10 @@ export function createControllerPromptInjector(deps: ControllerPromptDeps) {
     parts.push("");
     parts.push("### Available Roles");
     for (const role of ROLES) {
-      parts.push(`- ${role.icon} ${role.label}: ${role.description}`);
+      const skillLine = role.recommendedSkills.length > 0
+        ? ` Recommended skills: ${role.recommendedSkills.join(", ")}.`
+        : "";
+      parts.push(`- ${role.icon} ${role.label}: ${role.description}.${skillLine}`);
     }
 
     parts.push("");
@@ -89,6 +92,8 @@ export function createControllerPromptInjector(deps: ControllerPromptDeps) {
     parts.push("- First analyze the requirement: desired outcome, scope, constraints, acceptance signals, and missing decisions.");
     parts.push("- If critical information is missing, ask the human a concrete clarification question before creating execution tasks.");
     parts.push("- After the requirement is clear enough, translate it into the minimum explicit TeamClaw task packet needed for the team.");
+    parts.push("- When creating a task, include a recommendedSkills array whenever you know a useful OpenClaw/ClawHub skill slug (or a short search query if you do not know the exact slug).");
+    parts.push("- Prefer exact skill slugs over vague labels so the assigned worker can auto-search/install them before starting.");
     parts.push("- 'Minimum task packet' means only tasks that can start immediately with the currently available information and already-satisfied prerequisites.");
     parts.push("- If later phases depend on outputs that do not exist yet, describe them to the human as the plan, but do not create those TeamClaw tasks yet.");
     parts.push("- Downstream QA/review/release/README/integration tasks must stay in the plan until the upstream code or artifacts already exist in the workspace.");

package/src/controller/websocket.ts

@@ -5,6 +5,7 @@ import type { PluginLogger } from "../../api.js";
 export type WsEvent =
   | { type: "worker:online"; data: unknown }
   | { type: "worker:offline"; data: unknown }
+  | { type: "controller:run"; data: unknown }
   | { type: "task:created"; data: unknown }
   | { type: "task:updated"; data: unknown }
   | { type: "task:completed"; data: unknown }