@teamclaws/teamclaw 2026.3.26-2 → 2026.4.2-1

package/src/worker/http-handler.ts

@@ -4,10 +4,11 @@ import type { TaskAssignmentPayload, TeamMessage } from "../types.js";
 import { parseJsonBody, sendJson, sendError } from "../protocol.js";
 import { MessageQueue } from "./message-queue.js";
 
-export type TaskExecutor = (assignment: TaskAssignmentPayload) => Promise<string>;
-export type ResultReporter = (taskId: string, result: string, error: string | null) => void;
+export type TaskExecutor = (assignment: TaskAssignmentPayload) => Promise<string | { text: string; contract?: Record<string, unknown> }>;
+export type ResultReporter = (taskId: string, result: string, error: string | null, contract?: Record<string, unknown>) => void;
 export type TaskCanceller = (taskId: string) => Promise<boolean> | boolean;
 export type TaskCancelChecker = (taskId: string) => boolean;
+export type KickoffAssessor = (requirement: string, role: string) => Promise<Record<string, unknown>>;
 
 export function createWorkerHttpHandler(
   config: { role: string; port: number },
@@ -18,6 +19,7 @@ export function createWorkerHttpHandler(
   resultReporter?: ResultReporter,
   cancelTaskExecution?: TaskCanceller,
   isTaskCancelled?: TaskCancelChecker,
+  kickoffAssessor?: KickoffAssessor,
 ) {
   return async (req: IncomingMessage, res: ServerResponse) => {
     // CORS preflight
@@ -68,6 +70,9 @@ export function createWorkerHttpHandler(
         const executionIdempotencyKey = typeof body.executionIdempotencyKey === "string"
           ? body.executionIdempotencyKey
           : undefined;
+        const projectDir = typeof body.projectDir === "string"
+          ? body.projectDir
+          : undefined;
         const repo = body.repo && typeof body.repo === "object"
           ? body.repo as TaskAssignmentPayload["repo"]
           : undefined;
@@ -85,16 +90,18 @@ export function createWorkerHttpHandler(
               title,
               description,
               recommendedSkills,
+              projectDir,
               executionSessionKey,
               executionIdempotencyKey,
               repo,
             })
-            .then((result) => {
+            .then((raw) => {
               if (isTaskCancelled?.(taskId)) {
                 logger.info(`Worker: skipping result report for cancelled task ${taskId}`);
                 return;
               }
-              resultReporter(taskId, result, null);
+              const result = typeof raw === "string" ? { text: raw } : raw;
+              resultReporter(taskId, result.text, null, result.contract);
             })
             .catch((err) => {
               if (isTaskCancelled?.(taskId)) {
@@ -139,6 +146,35 @@ export function createWorkerHttpHandler(
         return;
       }
 
+      // POST /api/v1/kickoff/assess
+      if (req.method === "POST" && pathname === "/api/v1/kickoff/assess") {
+        if (!kickoffAssessor) {
+          sendError(res, 501, "Kickoff assessment is not supported by this worker");
+          return;
+        }
+
+        const body = await parseJsonBody(req);
+        const requirement = typeof body.requirement === "string" ? body.requirement : "";
+        const role = typeof body.role === "string" ? body.role : config.role;
+
+        if (!requirement) {
+          sendError(res, 400, "requirement is required");
+          return;
+        }
+
+        logger.info(`Worker: received kickoff assessment request for role ${role}`);
+
+        try {
+          const assessment = await kickoffAssessor(requirement, role);
+          sendJson(res, 200, { assessment });
+        } catch (err) {
+          const errorMsg = err instanceof Error ? err.message : String(err);
+          logger.error(`Worker: kickoff assessment failed: ${errorMsg}`);
+          sendError(res, 500, `Assessment failed: ${errorMsg}`);
+        }
+        return;
+      }
+
       sendError(res, 404, "Not found");
     } catch (err) {
       logger.error(`Worker HTTP error: ${err instanceof Error ? err.message : String(err)}`);

package/src/worker/prompt-injector.ts

@@ -1,20 +1,8 @@
 import type { PluginConfig, WorkerIdentity } from "../types.js";
 import { getRole } from "../roles.js";
+import { buildWorkerSessionRules, composePrompt } from "../prompt-policy.js";
 import { MessageQueue } from "./message-queue.js";
 
-const TEAMCLAW_ROLE_IDS_TEXT = [
-  "pm",
-  "architect",
-  "developer",
-  "qa",
-  "release-engineer",
-  "infra-engineer",
-  "devops",
-  "security-engineer",
-  "designer",
-  "marketing",
-].join(", ");
-
 export function createWorkerPromptInjector(
   config: PluginConfig,
   getIdentity: () => WorkerIdentity | null,
@@ -31,30 +19,13 @@ export function createWorkerPromptInjector(
       return null;
     }
 
-    const parts: string[] = [];
-
-    // Role context
-    parts.push(`## TeamClaw Role: ${roleDef.label} ${roleDef.icon}`);
-    parts.push(roleDef.systemPrompt);
-    parts.push("");
-    parts.push("## Current Session Rules");
-    parts.push("1. Complete only the task assigned to this session.");
-    parts.push("2. Pending team messages are context, not permission to widen scope.");
-    parts.push("3. Do NOT create new tasks, duplicate an existing task, or start a parallel task tree.");
-    parts.push("4. If you are blocked by missing information, raise a clarification request and stop instead of guessing.");
-    parts.push("5. If required infrastructure, credentials, or external tool access are unavailable in this runtime, raise a clarification request and stop instead of faking completion.");
-    parts.push("6. Respect the task's requested deliverable: briefs, plans, matrices, reviews, and design artifacts are not implementation requests unless the task explicitly asks you to build code.");
-    parts.push("7. If another role must continue later, use review/handoff tools on the current task instead of spawning work.");
-    parts.push("8. Other workers' OpenClaw sessions are isolated from this worker. Do not attempt cross-session inspection; use task context, the shared workspace, and queued team messages instead.");
-    parts.push("9. Do not mark the task completed or failed via progress updates. Return the final deliverable and let TeamClaw close the task.");
-    parts.push(`10. Valid TeamClaw role IDs: ${TEAMCLAW_ROLE_IDS_TEXT}.`);
-    parts.push("11. Treat file paths from documents, plans, and teammate messages as hints, not guarantees. Verify the real path exists in the current workspace before reading or editing it; if it does not exist, search for the closest real file and note the drift instead of repeatedly calling missing paths.");
-    parts.push("12. The workspace may be backed by a TeamClaw-managed git repository. Treat the current checkout as canonical project state; do not delete `.git` or replace the repo with ad-hoc archives.");
-    parts.push("13. If the assigned task includes recommended skills, use those exact skill slugs first. Missing skills should be searched/installed before execution when supported by the runtime.");
-    parts.push("14. Important: submit structured collaboration contracts, not only prose. Use teamclaw_submit_result_contract before your final reply, use structured fields on progress/handoff/review/message tools, and use clarification tools instead of hiding questions inside freeform output.");
-    parts.push("15. Do not use sessions_yield or end your turn while background work, coding agents, or process sessions are still running. A TeamClaw task is only done when you have the real final deliverable, not when a helper session is still working.");
-    parts.push(`Worker ID: ${identity.workerId}`);
-    parts.push(`Controller: ${identity.controllerUrl}`);
+    const parts: string[] = [
+      `## TeamClaw Role: ${roleDef.label} ${roleDef.icon}`,
+      roleDef.systemPrompt,
+      ...buildWorkerSessionRules(),
+      `Worker ID: ${identity.workerId}`,
+      `Controller: ${identity.controllerUrl}`,
+    ];
 
     // Pending messages
     const pendingMessages = messageQueue.peek();
@@ -69,7 +40,7 @@ export function createWorkerPromptInjector(
     }
 
     return {
-      prependSystemContext: parts.join("\n"),
+      prependSystemContext: composePrompt(parts),
     };
   };
 }

package/src/worker/skill-installer.ts

@@ -3,7 +3,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import type { PluginLogger } from "../../api.js";
 import { normalizeRecommendedSkills } from "../roles.js";
-import { resolveDefaultOpenClawWorkspaceDir } from "../openclaw-workspace.js";
+import { resolveTeamClawWorkspaceDir } from "../openclaw-workspace.js";
 import type { TaskAssignmentPayload, TaskExecutionEventInput } from "../types.js";
 
 type SkillCli = "openclaw" | "clawhub";
@@ -146,7 +146,7 @@ export async function installRecommendedSkills(
   logger: PluginLogger,
 ): Promise<SkillInstallResult> {
   const recommendedSkills = normalizeRecommendedSkills(assignment.recommendedSkills ?? []);
-  const workspaceDir = resolveDefaultOpenClawWorkspaceDir();
+  const workspaceDir = resolveTeamClawWorkspaceDir();
   const events: TaskExecutionEventInput[] = [];
   const installed: string[] = [];
   const skipped: string[] = [];

package/src/worker/tools.ts

@@ -11,6 +11,7 @@ import {
   renderWorkerProgressText,
 } from "../interaction-contracts.js";
 import type { PluginConfig, WorkerIdentity } from "../types.js";
+import { normalizeClarificationQuestionSchema } from "../controller/orchestration-manifest.js";
 
 const ALLOWED_PROGRESS_STATUSES = new Set(["in_progress", "review"]);
 
@@ -274,10 +275,15 @@ export function createWorkerTools(deps: WorkerToolsDeps) {
               kind: Type.String({ description: "Deliverable kind: file, directory, command, artifact, or note" }),
               value: Type.String({ description: "Deliverable identifier, path, or note" }),
               summary: Type.Optional(Type.String({ description: "Optional short note about this deliverable" })),
+              artifactType: Type.Optional(Type.String({ description: "Artifact type: web-app, static-site, binary, or document" })),
+              previewCommand: Type.Optional(Type.String({ description: "Command to start a live preview server (for web-app artifacts)" })),
+              previewCwd: Type.Optional(Type.String({ description: "Working directory for the preview command" })),
+              previewReadyPath: Type.Optional(Type.String({ description: "Path to poll for health (default /)" })),
             }),
           ),
         ),
         keyPoints: Type.Optional(Type.Array(Type.String({ description: "Important decisions, findings, or implementation notes" }))),
+        discoveredPatterns: Type.Optional(Type.Array(Type.String({ description: "Reusable codebase patterns discovered during this task (e.g. 'This codebase uses X for Y', 'Always update Z when changing W'). These are consolidated into workspace memory for future tasks." }))),
         blockers: Type.Optional(Type.Array(Type.String({ description: "Any unresolved blockers or risks" }))),
         followUps: Type.Optional(
           Type.Array(
@@ -308,6 +314,7 @@ export function createWorkerTools(deps: WorkerToolsDeps) {
           summary: params.summary,
           deliverables: params.deliverables,
           keyPoints: params.keyPoints,
+          discoveredPatterns: params.discoveredPatterns,
           blockers: params.blockers,
           followUps: params.followUps,
           questions: params.questions,
@@ -346,6 +353,23 @@ export function createWorkerTools(deps: WorkerToolsDeps) {
         question: Type.String({ description: "The exact question that must be answered before work can continue" }),
         blockingReason: Type.String({ description: "Why this task cannot proceed safely without clarification" }),
         context: Type.Optional(Type.String({ description: "Optional brief context or the specific decision that is missing" })),
+        questionSchema: Type.Optional(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 question must be answered" })),
+          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" })),
+          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" })),
+        })),
       }),
       async execute(_id: string, params: Record<string, unknown>) {
         const identity = getIdentity();
@@ -357,6 +381,7 @@ export function createWorkerTools(deps: WorkerToolsDeps) {
         const question = String(params.question ?? "");
         const blockingReason = String(params.blockingReason ?? "");
         const context = typeof params.context === "string" ? params.context : undefined;
+        const questionSchema = normalizeClarificationQuestionSchema(params.questionSchema);
 
         if (!taskId || !question || !blockingReason) {
           return { content: [{ type: "text" as const, text: "taskId, question, and blockingReason are required." }] };
@@ -370,11 +395,12 @@ export function createWorkerTools(deps: WorkerToolsDeps) {
               taskId,
               requestedBy: identity.workerId,
               requestedByWorkerId: identity.workerId,
-              requestedByRole: identity.role,
-              question,
-              blockingReason,
-              context,
-            }),
+               requestedByRole: identity.role,
+               question,
+               questionSchema,
+               blockingReason,
+               context,
+             }),
           });
 
           if (!res.ok) {

package/src/worker/worker-service.ts

@@ -5,13 +5,15 @@ import { createHeartbeatPayload } from "../protocol.js";
 import { IdentityManager } from "../identity.js";
 import { MessageQueue } from "./message-queue.js";
 import { createWorkerHttpHandler } from "./http-handler.js";
-import { ensureOpenClawWorkspaceMemoryDir } from "../openclaw-workspace.js";
+import { buildTeamClawAgentSessionKey, ensureOpenClawWorkspaceMemoryDir } from "../openclaw-workspace.js";
+
+export type TaskExecutorResultLike = string | { text: string; contract?: Record<string, unknown> };
 
 export type WorkerServiceDeps = {
   config: PluginConfig;
   logger: PluginLogger;
   onIdentityEstablished: (identity: WorkerIdentity) => void;
-  taskExecutor?: (taskDescription: string, assignment: TaskAssignmentPayload) => Promise<string>;
+  taskExecutor?: (taskDescription: string, assignment: TaskAssignmentPayload) => Promise<TaskExecutorResultLike>;
   prepareTaskAssignment?: (assignment: TaskAssignmentPayload) => Promise<void> | void;
   publishTaskAssignment?: (assignment: TaskAssignmentPayload, result: string) => Promise<void> | void;
   cancelTaskExecution?: (taskId: string, sessionKey?: string) => Promise<boolean> | boolean;
@@ -31,19 +33,20 @@ export function createWorkerService(deps: WorkerServiceDeps): OpenClawPluginServ
   const cancelledTaskIds = new Set<string>();
 
   const taskExecutor = externalTaskExecutor
-    ? async (assignment: TaskAssignmentPayload): Promise<string> => {
+    ? async (assignment: TaskAssignmentPayload): Promise<{ text: string; contract?: Record<string, unknown> }> => {
         const taskId = assignment.taskId;
         cancelledTaskIds.delete(taskId);
         activeTaskId = taskId;
-        activeTaskSessionKeys.set(taskId, assignment.executionSessionKey || `teamclaw-task-${taskId}`);
+        activeTaskSessionKeys.set(taskId, assignment.executionSessionKey || buildTeamClawAgentSessionKey(`teamclaw-task-${taskId}`));
         try {
           await deps.prepareTaskAssignment?.(assignment);
           const taskPrompt = [assignment.title.trim(), assignment.description.trim()].filter(Boolean).join("\n\n");
-          const result = await externalTaskExecutor(taskPrompt, assignment);
+          const raw = await externalTaskExecutor(taskPrompt, assignment);
           if (cancelledTaskIds.has(taskId)) {
             throw new Error("Task execution cancelled by controller");
           }
-          await deps.publishTaskAssignment?.(assignment, result);
+          const result = typeof raw === "string" ? { text: raw } : raw;
+          await deps.publishTaskAssignment?.(assignment, result.text);
           return result;
         } finally {
           activeTaskId = undefined;
@@ -55,16 +58,20 @@ export function createWorkerService(deps: WorkerServiceDeps): OpenClawPluginServ
       }
     : undefined;
 
-  function reportTaskResult(taskId: string, result: string, error: string | null): void {
+  function reportTaskResult(taskId: string, result: string, error: string | null, contract?: Record<string, unknown>): void {
     if (cancelledTaskIds.has(taskId)) {
       logger.info(`Worker: suppressing result report for cancelled task ${taskId}`);
       return;
     }
     if (!controllerUrl) return;
+    const body: Record<string, unknown> = { result, error, workerId };
+    if (contract) {
+      body.resultContract = contract;
+    }
     fetch(`${controllerUrl}/api/v1/tasks/${taskId}/result`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ result, error, workerId }),
+      body: JSON.stringify(body),
     }).catch((err) => {
       logger.error(`Worker: failed to report task result: ${String(err)}`);
     });
@@ -90,6 +97,39 @@ export function createWorkerService(deps: WorkerServiceDeps): OpenClawPluginServ
   }
 
   async function startServer(): Promise<void> {
+    // Kickoff assessor — uses the worker's subagent runtime for lightweight assessment
+    const kickoffAssessor = externalTaskExecutor
+      ? async (requirement: string, role: string): Promise<Record<string, unknown>> => {
+          const { buildKickoffAssessmentPrompt } = await import("../controller/kickoff-orchestrator.js");
+          const prompt = buildKickoffAssessmentPrompt(role as import("../types.js").RoleId, requirement);
+          const sessionKey = buildTeamClawAgentSessionKey(`teamclaw-kickoff-${role}-${Date.now()}`);
+          const raw = await externalTaskExecutor(prompt, {
+            taskId: `kickoff-${role}`,
+            title: `Kickoff Assessment (${role})`,
+            description: prompt,
+            executionSessionKey: sessionKey,
+          });
+          const text = typeof raw === "string" ? raw : raw.text;
+          // Parse the JSON response
+          const jsonMatch = text.match(/```(?:json)?\s*([\s\S]*?)```/) || text.match(/(\{[\s\S]*\})/);
+          const jsonStr = jsonMatch?.[1]?.trim() ?? text.trim();
+          try {
+            const parsed = JSON.parse(jsonStr);
+            return {
+              role,
+              needed: Boolean(parsed.needed),
+              scope: String(parsed.scope ?? ""),
+              suggestedTasks: Array.isArray(parsed.suggestedTasks) ? parsed.suggestedTasks : [],
+              dependencies: Array.isArray(parsed.dependencies) ? parsed.dependencies : [],
+              risks: Array.isArray(parsed.risks) ? parsed.risks : [],
+              questions: Array.isArray(parsed.questions) ? parsed.questions : [],
+            };
+          } catch {
+            return { role, needed: false, scope: `Could not parse: ${text.slice(0, 200)}`, suggestedTasks: [], dependencies: [], risks: [], questions: [] };
+          }
+        }
+      : undefined;
+
     const handler = createWorkerHttpHandler(
         { role: config.role, port: config.port },
         logger,
@@ -99,6 +139,7 @@ export function createWorkerService(deps: WorkerServiceDeps): OpenClawPluginServ
         reportTaskResult,
         cancelAssignedTask,
         isTaskCancelled,
+        kickoffAssessor,
       );
 
     if (server) {

package/src/workspace-browser.ts

@@ -1,6 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { resolveDefaultOpenClawWorkspaceDir } from "./openclaw-workspace.js";
+import { resolveTeamClawWorkspaceDir } from "./openclaw-workspace.js";
 
 const MAX_PREVIEW_BYTES = 256 * 1024;
 const MAX_TREE_DEPTH = 8;
@@ -81,15 +81,25 @@ export type WorkspaceFilePayload = {
   contentType: string;
 };
 
-export async function listWorkspaceTree(): Promise<WorkspaceTreePayload> {
+export async function listWorkspaceTree(maxDepth?: number): Promise<WorkspaceTreePayload> {
   const workspaceDir = await ensureWorkspaceDir();
-  const entries = await readTree(workspaceDir, "", 0);
+  const entries = await readTree(workspaceDir, "", 0, maxDepth);
   return {
     root: "/",
     entries,
   };
 }
 
+/** Load children of a single directory (one level). Used for lazy-loading. */
+export async function listWorkspaceSubtree(relativePath: string): Promise<WorkspaceTreeNode[]> {
+  const { absolutePath, normalizedPath } = await resolveWorkspacePath(relativePath);
+  const stat = await fs.stat(absolutePath);
+  if (!stat.isDirectory()) {
+    throw new Error("Path is not a directory");
+  }
+  return readTree(absolutePath, normalizedPath, 0, 1);
+}
+
 export async function readWorkspaceFile(relativePath: string): Promise<WorkspaceFilePayload> {
   const { normalizedPath, absolutePath } = await resolveWorkspacePath(relativePath);
   const stat = await fs.stat(absolutePath);
@@ -147,7 +157,7 @@ export function buildWorkspaceRawUrl(relativePath: string): string {
 }
 
 async function ensureWorkspaceDir(): Promise<string> {
-  const workspaceDir = resolveDefaultOpenClawWorkspaceDir();
+  const workspaceDir = resolveTeamClawWorkspaceDir();
   await fs.mkdir(workspaceDir, { recursive: true });
   return workspaceDir;
 }
@@ -189,8 +199,9 @@ function normalizeWorkspacePath(relativePath: string): string {
   return normalized;
 }
 
-async function readTree(dirPath: string, relativeDir: string, depth: number): Promise<WorkspaceTreeNode[]> {
-  if (depth > MAX_TREE_DEPTH) {
+async function readTree(dirPath: string, relativeDir: string, depth: number, maxDepth?: number): Promise<WorkspaceTreeNode[]> {
+  const effectiveMaxDepth = maxDepth ?? MAX_TREE_DEPTH;
+  if (depth > effectiveMaxDepth) {
     return [];
   }
 
@@ -209,11 +220,13 @@ async function readTree(dirPath: string, relativeDir: string, depth: number): Pr
     const childAbsolutePath = path.join(dirPath, dirent.name);
 
     if (dirent.isDirectory()) {
+      // At max depth, mark directory as lazy-loadable (no children yet)
+      const atLimit = depth + 1 > effectiveMaxDepth;
       nodes.push({
         name: dirent.name,
         path: childRelativePath,
         type: "directory",
-        children: await readTree(childAbsolutePath, childRelativePath, depth + 1),
+        children: atLimit ? undefined : await readTree(childAbsolutePath, childRelativePath, depth + 1, effectiveMaxDepth),
       });
       continue;
     }