@teamclaws/teamclaw 2026.3.26-2 → 2026.4.2-1

package/src/task-executor.ts

@@ -1,19 +1,18 @@
 import type { OpenClawPluginApi, PluginLogger } from "../api.js";
+import {
+  buildDeliverableMetadataPolicy,
+  buildResultContractGuidance,
+  buildTaskExecutionRules,
+  buildVerificationPolicy,
+  buildWorkerMemoryContractRules,
+} from "./prompt-policy.js";
+import {
+  buildTeamClawProjectWorkspacePath,
+  resolveTeamClawWorkspaceDir,
+  resolveTeamClawProjectsDir,
+} from "./openclaw-workspace.js";
 import { getRole } from "./roles.js";
-import type { RoleId, TaskAssignmentPayload, TaskExecutionEventInput } from "./types.js";
-
-const TEAMCLAW_ROLE_IDS_TEXT = [
-  "pm",
-  "architect",
-  "developer",
-  "qa",
-  "release-engineer",
-  "infra-engineer",
-  "devops",
-  "security-engineer",
-  "designer",
-  "marketing",
-].join(", ");
+import type { RoleId, TaskAssignmentPayload, TaskExecutionEventInput, WorkerTaskResultContract } from "./types.js";
 
 const SESSION_PROGRESS_POLL_INTERVAL_MS = 1000;
 const SESSION_PROGRESS_MESSAGE_LIMIT = 200;
@@ -23,6 +22,7 @@ const RATE_LIMIT_STALL_PROBE_MS = 5 * 60 * 1000;
 const RATE_LIMIT_PROBE_TIMEOUT_MS = 60_000;
 const BACKGROUND_WORK_PROBE_MS = 60_000;
 const BACKGROUND_WORK_PROBE_TIMEOUT_MS = 60_000;
+const INACTIVITY_PROBE_TIMEOUT_MS = 60_000;
 const CHILD_SESSION_PROGRESS_POLL_INTERVAL_MS = 5_000;
 const RATE_LIMIT_WAITING_SENTINEL = "TEAMCLAW_STILL_WAITING";
 const TOOL_CALL_BLOCK_TYPES = new Set(["tool_use", "toolcall", "tool_call"]);
@@ -43,6 +43,7 @@ type SessionProgressSnapshot = {
   lastChildPollAt: number;
   lastAssistantMessage: string;
   latestMessages: unknown[];
+  lastActivityAt: number;
 };
 
 type AssistantTurnSnapshot = {
@@ -52,6 +53,11 @@ type AssistantTurnSnapshot = {
   backgroundPending: boolean;
 };
 
+export type TaskExecutorResult = {
+  text: string;
+  contract?: Record<string, unknown>;
+};
+
 export type RoleTaskExecutorDeps = {
   runtime: OpenClawPluginApi["runtime"];
   logger: PluginLogger;
@@ -69,13 +75,27 @@ export function createRoleTaskExecutor(deps: RoleTaskExecutorDeps) {
     ? roleDef.systemPrompt
     : `You are a ${role} in a virtual software team. Complete the assigned task.`;
 
-  return async (taskDescription: string, assignment: TaskAssignmentPayload): Promise<string> => {
+  return async (taskDescription: string, assignment: TaskAssignmentPayload): Promise<TaskExecutorResult> => {
     const taskId = assignment.taskId;
     const sessionKey = getSessionKey(assignment);
     const idempotencyKey = getIdempotencyKey?.(assignment);
-    const taskMessage = buildTaskMessage(taskDescription, taskId, roleDef?.label ?? role);
+    const taskMessage = buildTaskMessage(taskDescription, taskId, roleDef?.label ?? role, {
+      inlineContract: true,
+      projectDir: assignment.projectDir,
+    });
+    const workspaceDir = resolveTeamClawWorkspaceDir();
     logger.info(`TeamClaw: executing task ${taskId} as ${role} via subagent`);
 
+    function buildSubagentRunOptions(
+      options: Parameters<typeof runtime.subagent.run>[0],
+    ): Parameters<typeof runtime.subagent.run>[0] {
+      const enrichedOptions: Parameters<typeof runtime.subagent.run>[0] & { workspaceDir?: string } = {
+        ...options,
+        workspaceDir,
+      };
+      return enrichedOptions;
+    }
+
     async function emitExecutionEvent(event: TaskExecutionEventInput): Promise<void> {
       if (!reportExecutionEvent) {
         return;
@@ -92,12 +112,12 @@ export function createRoleTaskExecutor(deps: RoleTaskExecutorDeps) {
     }
 
     try {
-      const runResult = await runtime.subagent.run({
+      const runResult = await runtime.subagent.run(buildSubagentRunOptions({
         sessionKey,
         message: taskMessage,
         extraSystemPrompt: roleSystemPrompt,
         idempotencyKey,
-      });
+      }));
 
       logger.info(`TeamClaw: subagent run started for task ${taskId}, runId=${runResult.runId}`);
       await emitExecutionEvent({
@@ -117,8 +137,8 @@ export function createRoleTaskExecutor(deps: RoleTaskExecutorDeps) {
         lastChildPollAt: 0,
         lastAssistantMessage: "",
         latestMessages: [],
+        lastActivityAt: Date.now(),
       };
-      const deadline = Date.now() + taskTimeoutMs;
       const rateLimitState: {
         active: boolean;
         visibleAt?: number;
@@ -128,6 +148,24 @@ export function createRoleTaskExecutor(deps: RoleTaskExecutorDeps) {
         active: false,
         probeCount: 0,
       };
+      const inactivityState: {
+        active: boolean;
+        visibleAt?: number;
+        nextProbeAt?: number;
+        probeCount: number;
+      } = {
+        active: false,
+        nextProbeAt: Date.now() + taskTimeoutMs,
+        probeCount: 0,
+      };
+
+      const noteObservedActivity = (): void => {
+        const now = Date.now();
+        progressSnapshot.lastActivityAt = now;
+        inactivityState.active = false;
+        inactivityState.visibleAt = undefined;
+        inactivityState.nextProbeAt = now + taskTimeoutMs;
+      };
       const backgroundWaitState: {
         active: boolean;
         visibleAt?: number;
@@ -198,6 +236,9 @@ export function createRoleTaskExecutor(deps: RoleTaskExecutorDeps) {
         const entries = buildSessionProgressEntries(progressSnapshot.latestMessages, taskMessage);
         const newEntries = getNewSessionProgressEntries(entries, progressSnapshot.fingerprints);
         progressSnapshot.fingerprints = entries.map((entry) => entry.fingerprint);
+        if (newEntries.length > 0) {
+          noteObservedActivity();
+        }
         progressSnapshot.childSessionKeys = mergeChildSessionKeys(
           progressSnapshot.childSessionKeys,
           collectChildSessionKeys(progressSnapshot.latestMessages),
@@ -268,12 +309,12 @@ export function createRoleTaskExecutor(deps: RoleTaskExecutorDeps) {
           message: `Model rate limit has delayed task progress for over ${formatDuration(RATE_LIMIT_STALL_PROBE_MS)}. Re-checking whether the current task has already completed.`,
         });
 
-        const probeRun = await runtime.subagent.run({
+        const probeRun = await runtime.subagent.run(buildSubagentRunOptions({
           sessionKey,
           message: buildRateLimitProbeMessage(taskId, roleDef?.label ?? role),
           extraSystemPrompt: roleSystemPrompt,
           idempotencyKey: `${idempotencyKey ?? `teamclaw-${taskId}`}:rate-limit-probe:${rateLimitState.probeCount}`,
-        });
+        }));
         const probeWait = await runtime.subagent.waitForRun({
           runId: probeRun.runId,
           timeoutMs: RATE_LIMIT_PROBE_TIMEOUT_MS,
@@ -322,18 +363,15 @@ export function createRoleTaskExecutor(deps: RoleTaskExecutorDeps) {
           message: `Background work has been running for over ${formatDuration(BACKGROUND_WORK_PROBE_MS)}. Re-checking whether the original task is now complete.`,
         });
 
-        const probeRun = await runtime.subagent.run({
+        const probeRun = await runtime.subagent.run(buildSubagentRunOptions({
           sessionKey,
           message: buildBackgroundWorkProbeMessage(taskId, roleDef?.label ?? role),
           extraSystemPrompt: roleSystemPrompt,
           idempotencyKey: `${idempotencyKey ?? `teamclaw-${taskId}`}:background-work-probe:${backgroundWaitState.probeCount}`,
-        });
+        }));
         const probeWait = await runtime.subagent.waitForRun({
           runId: probeRun.runId,
-          timeoutMs: Math.min(
-            BACKGROUND_WORK_PROBE_TIMEOUT_MS,
-            Math.max(1_000, deadline - Date.now()),
-          ),
+          timeoutMs: BACKGROUND_WORK_PROBE_TIMEOUT_MS,
         });
 
         try {
@@ -372,6 +410,71 @@ export function createRoleTaskExecutor(deps: RoleTaskExecutorDeps) {
         return probeTurn;
       };
 
+      const probeInactiveTaskCompletion = async (): Promise<AssistantTurnSnapshot | null> => {
+        inactivityState.probeCount += 1;
+        const now = Date.now();
+        inactivityState.active = true;
+        inactivityState.visibleAt = now;
+        inactivityState.nextProbeAt = now + taskTimeoutMs;
+        await emitExecutionEvent({
+          type: "progress",
+          phase: "inactivity_probe",
+          source: "worker",
+          status: "running",
+          runId: runResult.runId,
+          sessionKey,
+          message: `No new visible task progress has appeared for over ${formatDuration(taskTimeoutMs)}. Re-checking whether the original task is complete or still actively running.`,
+        });
+
+        const probeRun = await runtime.subagent.run(buildSubagentRunOptions({
+          sessionKey,
+          message: buildInactivityProbeMessage(taskId, roleDef?.label ?? role, taskTimeoutMs),
+          extraSystemPrompt: roleSystemPrompt,
+          idempotencyKey: `${idempotencyKey ?? `teamclaw-${taskId}`}:inactivity-probe:${inactivityState.probeCount}`,
+        }));
+        const probeWait = await runtime.subagent.waitForRun({
+          runId: probeRun.runId,
+          timeoutMs: INACTIVITY_PROBE_TIMEOUT_MS,
+        });
+
+        try {
+          await syncSessionProgress();
+        } catch (err) {
+          logger.debug?.(`TeamClaw: failed inactivity probe session sync for ${taskId}: ${String(err)}`);
+        }
+
+        if (probeWait.status === "error" && isRateLimitMessage(probeWait.error || "")) {
+          await markRateLimitWaiting();
+          return null;
+        }
+        if (probeWait.status !== "ok") {
+          return null;
+        }
+
+        const probeTurn = await extractSessionAssistantTurn();
+        if (!probeTurn.text || probeTurn.backgroundPending || isRateLimitMessage(probeTurn.text) || isStillWaitingResponse(probeTurn.text)) {
+          inactivityState.active = false;
+          inactivityState.visibleAt = undefined;
+          inactivityState.nextProbeAt = Date.now() + taskTimeoutMs;
+          await emitExecutionEvent({
+            type: "progress",
+            phase: "inactivity_still_waiting",
+            source: "worker",
+            status: "running",
+            runId: runResult.runId,
+            sessionKey,
+            message: "The task is still actively pending with no final result yet. TeamClaw will continue waiting instead of failing it.",
+          });
+          return null;
+        }
+
+        if (rateLimitState.active) {
+          clearRateLimitWaiting();
+        }
+        noteObservedActivity();
+        return probeTurn;
+      };
+
       let keepPolling = true;
       const pollSessionProgress = (async () => {
         while (keepPolling) {
@@ -392,12 +495,6 @@ export function createRoleTaskExecutor(deps: RoleTaskExecutorDeps) {
       let completionOverride: string | null = null;
       try {
         while (true) {
-          const remainingMs = deadline - Date.now();
-          if (remainingMs <= 0) {
-            waitResult = { status: "timeout" as const };
-            break;
-          }
-
           if (rateLimitState.active && (rateLimitState.nextProbeAt ?? Number.POSITIVE_INFINITY) <= Date.now()) {
             completionOverride = await probeRateLimitedTaskCompletion();
             if (completionOverride) {
@@ -406,10 +503,22 @@ export function createRoleTaskExecutor(deps: RoleTaskExecutorDeps) {
             }
           }
 
-          const sliceTimeoutMs = Math.max(1_000, Math.min(RUN_WAIT_SLICE_MS, remainingMs));
+          if (
+            !rateLimitState.active
+            && !backgroundWaitState.active
+            && (inactivityState.nextProbeAt ?? Number.POSITIVE_INFINITY) <= Date.now()
+          ) {
+            const inactivityProbeTurn = await probeInactiveTaskCompletion();
+            if (inactivityProbeTurn) {
+              completionOverride = inactivityProbeTurn.text;
+              waitResult = { status: "ok" as const };
+              break;
+            }
+          }
+
           waitResult = await runtime.subagent.waitForRun({
             runId: runResult.runId,
-            timeoutMs: sliceTimeoutMs,
+            timeoutMs: RUN_WAIT_SLICE_MS,
           });
 
           if (waitResult.status === "ok") {
@@ -440,13 +549,8 @@ export function createRoleTaskExecutor(deps: RoleTaskExecutorDeps) {
           : await extractSessionAssistantTurn();
         while (isBackgroundWorkPendingTurn(assistantTurn)) {
           await markBackgroundWorkWaiting();
-          const remainingMs = deadline - Date.now();
-          if (remainingMs <= 0) {
-            waitResult = { status: "timeout" as const };
-            break;
-          }
           const nextProbeAt = backgroundWaitState.nextProbeAt ?? (Date.now() + BACKGROUND_WORK_PROBE_MS);
-          const delayMs = Math.max(1_000, Math.min(nextProbeAt - Date.now(), remainingMs));
+          const delayMs = Math.max(1_000, nextProbeAt - Date.now());
           await delay(delayMs);
           const probeTurn = await probeBackgroundTaskCompletion();
           if (probeTurn) {
@@ -459,34 +563,37 @@ export function createRoleTaskExecutor(deps: RoleTaskExecutorDeps) {
           if (rateLimitState.active) {
             clearRateLimitWaiting();
           }
-          const result = assistantTurn.text;
-          if (result && normalizeComparableText(result) !== normalizeComparableText(progressSnapshot.lastAssistantMessage)) {
+          const rawResult = assistantTurn.text;
+          if (rawResult && normalizeComparableText(rawResult) !== normalizeComparableText(progressSnapshot.lastAssistantMessage)) {
             await emitExecutionEvent({
               type: "output",
               phase: "final_output",
               source: "subagent",
-              message: result,
+              message: rawResult,
             });
           }
 
           clearBackgroundWorkWaiting();
+
+          // Extract inline result contract if present
+          const extracted = extractInlineResultContract(rawResult);
+          if (extracted) {
+            logger.info(`TeamClaw: task ${taskId} — extracted inline result contract from ${role}`);
+            return { text: extracted.cleanedText || rawResult, contract: extracted.contract };
+          }
+          if (rawResult && isApprovalRequiredResponse(rawResult)) {
+            logger.warn(`TeamClaw: task ${taskId} is blocked waiting for exec approval as ${role}`);
+            return {
+              text: rawResult,
+              contract: buildApprovalBlockedContract(rawResult),
+            };
+          }
           logger.info(`TeamClaw: task ${taskId} completed successfully as ${role}`);
-          return result;
+          return { text: rawResult };
         }
         clearBackgroundWorkWaiting();
       }
 
-      if (waitResult.status === "timeout") {
-        await emitExecutionEvent({
-          type: "error",
-          phase: "timeout",
-          source: "subagent",
-          status: "failed",
-          message: `Task execution timed out after ${formatDuration(taskTimeoutMs)}`,
-        });
-        throw new Error(`Task execution timed out after ${formatDuration(taskTimeoutMs)}`);
-      }
-
       await emitExecutionEvent({
         type: "error",
         phase: "run_failed",
@@ -780,33 +887,80 @@ function safeJsonStringify(value: unknown): string {
   }
 }
 
-function buildTaskMessage(taskDescription: string, taskId: string, roleLabel: string): string {
-  return [
+function buildTaskMessage(
+  taskDescription: string,
+  taskId: string,
+  roleLabel: string,
+  options?: { inlineContract?: boolean; projectDir?: string },
+): string {
+  const rules = [
+    ...buildTaskExecutionRules(RATE_LIMIT_WAITING_SENTINEL),
+    ...buildWorkerMemoryContractRules(),
+    ...buildVerificationPolicy(),
+    ...buildDeliverableMetadataPolicy(),
+    ...buildResultContractGuidance({ inlineContract: Boolean(options?.inlineContract) }),
+  ];
+
+  const sections = [
     taskDescription,
     "",
     "## Task Context",
     `Reference: ${taskId}`,
     `Assigned Role: ${roleLabel}`,
-    "",
-    "## Execution Rules",
-    "- Deliver exactly the artifact requested by this task.",
-    "- Follow the task verb literally: if the task asks for a brief, plan, matrix, review, package, positioning, or design artifact, produce that artifact and stop there.",
-    "- Do NOT scaffold code, project structure, configs, or files unless the task explicitly asks for implementation work.",
-    "- Do NOT create additional tasks, task trees, or duplicate follow-up work.",
-    "- Do NOT re-scope this into a multi-role coordination workflow.",
-    "- Do NOT delegate the core work of this task away to another role.",
-    "- If Task Context includes recent completed deliverables, treat them as upstream inputs and search the shared workspace for any referenced task IDs or filenames before requesting clarification.",
-    "- Do NOT attempt to inspect or resolve another worker's OpenClaw session or session key; those sessions are isolated per worker.",
-    "- If the task includes a Recommended Skills section, use those skills first and prefer the exact listed slugs when searching for additional help.",
-    "- Do NOT mark the task completed or failed via progress tools. Return the final deliverable (or raise an error) and let TeamClaw close the task.",
-    "- If critical information is missing and you cannot proceed safely, request clarification and wait instead of guessing.",
-    "- If more work is needed, mention it briefly in your result or use a handoff/review tool on this same task.",
-    "- Before your final reply, submit a structured worker result contract with teamclaw_submit_result_contract so TeamClaw can route the next step without parsing prose.",
-    `- Do NOT use sessions_yield or end your turn while background work, coding agents, or process sessions are still running; if the task is not complete yet, reply with exactly ${RATE_LIMIT_WAITING_SENTINEL}.`,
-    "- Never return 'running in background' as the final result for a TeamClaw task. If you spawn a helper session, keep monitoring it and only return after you have the actual deliverable.",
-    "- Use structured fields on progress, review, handoff, and messaging tools whenever coordination is needed.",
-    `- When naming a role, use exact TeamClaw role IDs: ${TEAMCLAW_ROLE_IDS_TEXT}.`,
-  ].join("\n");
+  ];
+
+  if (options?.projectDir) {
+    const workspaceProjectPath = buildTeamClawProjectWorkspacePath(options.projectDir);
+    const absoluteProjectPath = `${resolveTeamClawProjectsDir()}/${options.projectDir}`.replace(/\/+/gu, "/");
+    sections.push(
+      "",
+      "## Working Directory",
+      `This task's project directory is: \`${workspaceProjectPath}/\``,
+      `Authoritative absolute path: \`${absoluteProjectPath}/\``,
+      "All files you create, read, or modify for this task MUST be inside this directory.",
+      "If the directory is empty, create the necessary structure. If it already has files from prior tasks in the same project, build on them.",
+      "If the task description mentions a different absolute workspace path, treat that path as stale guidance and use this authoritative project directory instead.",
+      "When the task references project-local files such as `ARCHITECTURE.md`, `README.md`, or `package.json`, resolve them inside this project directory first.",
+      "Do NOT place files in the workspace root or any other project's directory.",
+    );
+  }
+
+  sections.push("", "## Execution Rules", ...rules);
+  return sections.join("\n");
+}
+
+/**
+ * Extract an inline result contract from a fenced ```teamclaw-result-contract block.
+ * Returns the parsed contract and the text with the block removed, or null if
+ * no valid contract is found.
+ */
+export function extractInlineResultContract(text: string): {
+  contract: Record<string, unknown>;
+  cleanedText: string;
+} | null {
+  // Match ```teamclaw-result-contract ... ``` blocks (greedy last match)
+  const pattern = /```teamclaw-result-contract\s*\n([\s\S]*?)```/g;
+  let lastMatch: RegExpExecArray | null = null;
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(text)) !== null) {
+    lastMatch = match;
+  }
+  if (!lastMatch) {
+    return null;
+  }
+  const jsonStr = lastMatch[1]!.trim();
+  try {
+    const parsed = JSON.parse(jsonStr);
+    if (!parsed || typeof parsed !== "object") {
+      return null;
+    }
+    // Remove the contract block from the text for a clean result
+    const cleanedText = text.slice(0, lastMatch.index).trimEnd()
+      + text.slice(lastMatch.index + lastMatch[0].length).trimStart();
+    return { contract: parsed, cleanedText: cleanedText.trim() };
+  } catch {
+    return null;
+  }
 }
 
 function buildRateLimitProbeMessage(taskId: string, roleLabel: string): string {
@@ -831,6 +985,17 @@ function buildBackgroundWorkProbeMessage(taskId: string, roleLabel: string): str
   ].join("\n");
 }
 
+function buildInactivityProbeMessage(taskId: string, roleLabel: string, inactivityMs: number): string {
+  return [
+    `This is a follow-up check for task ${taskId} (${roleLabel}).`,
+    `There has been no new visible progress for over ${formatDuration(inactivityMs)}.`,
+    "Do not restart the task from scratch.",
+    "Continue from the existing workspace and session state only.",
+    "If the original task is fully complete now, immediately submit the structured result contract and provide the final result for that original task.",
+    `If the original task is not complete yet, reply with exactly ${RATE_LIMIT_WAITING_SENTINEL}.`,
+  ].join("\n");
+}
+
 function buildAssistantTurnSnapshot(text: string, toolCalls: string[] = []): AssistantTurnSnapshot {
   const normalizedText = String(text || "").trim();
   const normalizedToolCalls = toolCalls
@@ -902,6 +1067,45 @@ function isStillWaitingResponse(value: string): boolean {
   return /(still waiting|continue waiting|not complete yet|尚未完成|继续等待|仍在等待)/i.test(normalized);
 }
 
+function extractPendingApprovalCommands(value: string): string[] {
+  const matches = String(value || "").match(/\/approve\s+[^\s]+\s+(?:allow-once|allow-always|deny)\b/gi) ?? [];
+  return Array.from(new Set(matches.map((entry) => entry.trim()).filter(Boolean)));
+}
+
+function isApprovalRequiredResponse(value: string): boolean {
+  const normalized = String(value || "").trim();
+  if (!normalized) {
+    return false;
+  }
+  return /approval required|i need approval to run commands|pending exec commands?|reply with:\s*\/approve|需要批准|等待.*批准/i.test(normalized)
+    || extractPendingApprovalCommands(normalized).length > 0;
+}
+
+function buildApprovalBlockedContract(rawResult: string): WorkerTaskResultContract {
+  const approvalCommands = extractPendingApprovalCommands(rawResult);
+  const blockingReason = "Pending exec approval is required before this task can continue.";
+  return {
+    version: "1.0",
+    outcome: "blocked",
+    summary: "Task is blocked waiting for exec approval.",
+    deliverables: approvalCommands.map((command) => ({
+      kind: "command",
+      value: command,
+      summary: "Approval command emitted by the worker runtime.",
+    })),
+    keyPoints: approvalCommands,
+    blockers: [blockingReason],
+    followUps: [{
+      type: "clarification",
+      reason: blockingReason,
+    }],
+    questions: [
+      "A worker command needs exec approval before this task can continue. Should TeamClaw retry after the approval policy is fixed or the commands are approved?",
+    ],
+    notes: rawResult,
+  };
+}
+
 function isInternalRetryPrompt(value: string, stream?: string): boolean {
   if (stream !== "user") {
     return false;