@teamclaws/teamclaw 2026.3.25 → 2026.3.26-1

package/src/controller/orchestration-manifest.ts

@@ -0,0 +1,105 @@
+import type {
+  ControllerManifestCreatedTask,
+  ControllerManifestDeferredTask,
+  ControllerOrchestrationManifest,
+  RoleId,
+} from "../types.js";
+
+const TEAMCLAW_ROLE_IDS = new Set<RoleId>([
+  "pm",
+  "architect",
+  "developer",
+  "qa",
+  "release-engineer",
+  "infra-engineer",
+  "devops",
+  "security-engineer",
+  "designer",
+  "marketing",
+]);
+
+export function normalizeManifestRoleList(raw: unknown): RoleId[] {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  const roleIds: RoleId[] = [];
+  for (const entry of raw) {
+    if (typeof entry !== "string") {
+      continue;
+    }
+    const normalized = entry.trim() as RoleId;
+    if (!normalized || !TEAMCLAW_ROLE_IDS.has(normalized) || roleIds.includes(normalized)) {
+      continue;
+    }
+    roleIds.push(normalized);
+  }
+  return roleIds;
+}
+
+export function normalizeManifestStringList(raw: unknown): string[] {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  return raw
+    .map((entry) => (typeof entry === "string" ? entry.trim() : ""))
+    .filter(Boolean);
+}
+
+export function normalizeOptionalManifestText(raw: unknown): string | undefined {
+  if (typeof raw !== "string") {
+    return undefined;
+  }
+  const normalized = raw.trim();
+  return normalized || undefined;
+}
+
+export function normalizeManifestCreatedTasks(raw: unknown): ControllerManifestCreatedTask[] {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  return raw
+    .filter((entry): entry is Record<string, unknown> => !!entry && typeof entry === "object")
+    .map((entry) => ({
+      title: typeof entry.title === "string" ? entry.title.trim() : "",
+      assignedRole: normalizeManifestRoleList([entry.assignedRole])[0],
+      expectedOutcome: typeof entry.expectedOutcome === "string" ? entry.expectedOutcome.trim() : "",
+    }))
+    .filter((entry) => entry.title && entry.expectedOutcome);
+}
+
+export function normalizeManifestDeferredTasks(raw: unknown): ControllerManifestDeferredTask[] {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  return raw
+    .filter((entry): entry is Record<string, unknown> => !!entry && typeof entry === "object")
+    .map((entry) => ({
+      title: typeof entry.title === "string" ? entry.title.trim() : "",
+      assignedRole: normalizeManifestRoleList([entry.assignedRole])[0],
+      blockedBy: typeof entry.blockedBy === "string" ? entry.blockedBy.trim() : "",
+      whenReady: typeof entry.whenReady === "string" ? entry.whenReady.trim() : "",
+    }))
+    .filter((entry) => entry.title && entry.blockedBy && entry.whenReady);
+}
+
+export function normalizeControllerManifest(raw: unknown): ControllerOrchestrationManifest | null {
+  if (!raw || typeof raw !== "object") {
+    return null;
+  }
+  const input = raw as Record<string, unknown>;
+  const requirementSummary = typeof input.requirementSummary === "string" ? input.requirementSummary.trim() : "";
+  if (!requirementSummary) {
+    return null;
+  }
+  return {
+    version: typeof input.version === "string" && input.version.trim() ? input.version.trim() : "1.0",
+    requirementSummary,
+    requiredRoles: normalizeManifestRoleList(input.requiredRoles),
+    clarificationsNeeded: Boolean(input.clarificationsNeeded),
+    clarificationQuestions: normalizeManifestStringList(input.clarificationQuestions),
+    createdTasks: normalizeManifestCreatedTasks(input.createdTasks),
+    deferredTasks: normalizeManifestDeferredTasks(input.deferredTasks),
+    handoffPlan: normalizeOptionalManifestText(input.handoffPlan),
+    notes: normalizeOptionalManifestText(input.notes),
+  };
+}

package/src/controller/prompt-injector.ts

@@ -1,5 +1,6 @@
 import type { PluginConfig, TeamState } from "../types.js";
 import { ROLES } from "../roles.js";
+import { hasOnDemandWorkerProvisioning, shouldBlockControllerWithoutWorkers } from "./controller-capacity.js";
 
 const TEAMCLAW_ROLE_IDS_TEXT = [
   "pm",
@@ -22,15 +23,13 @@ export type ControllerPromptDeps = {
 export function createControllerPromptInjector(deps: ControllerPromptDeps) {
   return () => {
     const state = deps.getTeamState();
-    if (!state) return null;
-
-    const workers = Object.values(state.workers);
-    const tasks = Object.values(state.tasks);
+    const workers = Object.values(state?.workers ?? {});
+    const tasks = Object.values(state?.tasks ?? {});
     const pendingTasks = tasks.filter((t) => t.status === "pending");
     const activeTasks = tasks.filter((t) => t.status === "in_progress" || t.status === "assigned");
     const blockedTasks = tasks.filter((t) => t.status === "blocked");
     const completedTasks = tasks.filter((t) => t.status === "completed");
-    const pendingClarifications = Object.values(state.clarifications).filter((c) => c.status === "pending");
+    const pendingClarifications = Object.values(state?.clarifications ?? {}).filter((c) => c.status === "pending");
 
     const parts: string[] = [
       "## TeamClaw Controller Mode",
@@ -39,6 +38,7 @@ export function createControllerPromptInjector(deps: ControllerPromptDeps) {
       "",
       "### Available Tools",
       "- teamclaw_create_task: Create a new task with role assignment",
+      "- teamclaw_submit_manifest: Submit the required structured orchestration manifest for this intake run",
       "- teamclaw_list_tasks: List all tasks with status filtering",
       "- teamclaw_assign_task: Assign a task to a specific worker",
       "- teamclaw_send_message: Send messages between team members",
@@ -46,8 +46,17 @@ export function createControllerPromptInjector(deps: ControllerPromptDeps) {
       "### Current Team Status",
     ];
 
-    if (workers.length === 0) {
-      parts.push("- No workers registered yet");
+    if (!state) {
+      parts.push("- Team state is not loaded yet; treat this as a fresh controller intake and establish execution-ready tasks from the human requirement.");
+    } else if (workers.length === 0) {
+      if (shouldBlockControllerWithoutWorkers(deps.config, state)) {
+        parts.push("- No workers are registered and on-demand provisioning is disabled.");
+        parts.push("- Blocking rule: you may analyze the requirement and identify the needed roles, but do not create TeamClaw tasks yet.");
+        parts.push("- Do not start doing the worker-role work yourself. Tell the human to bring workers online or enable process/docker/kubernetes provisioning first.");
+      } else {
+        parts.push("- No workers are registered yet, but on-demand provisioning is enabled.");
+        parts.push("- You may still create execution-ready TeamClaw tasks for the required roles; the controller will provision workers on demand.");
+      }
     } else {
       for (const w of workers) {
         const roleDef = ROLES.find((r) => r.id === w.role);
@@ -86,6 +95,24 @@ export function createControllerPromptInjector(deps: ControllerPromptDeps) {
       parts.push(`- ${role.icon} ${role.label}: ${role.description}.${skillLine}`);
     }
 
+    parts.push("");
+    parts.push("## Controller Workflow");
+    parts.push("- First determine which TeamClaw roles are needed for the human requirement.");
+    parts.push("- Then translate the requirement into the minimum execution-ready TeamClaw tasks owned by those roles.");
+    parts.push("- TeamClaw workers, not the controller, do the specialist work in the shared repo/workspace.");
+    parts.push("- After workers report progress, results, or handoffs, create only the next tasks whose prerequisites are now satisfied.");
+    parts.push("- A completed upstream task with a structured result contract, concrete deliverables, or an explicit handoff is strong evidence that its dependent downstream work can now be created.");
+
+    parts.push("");
+    parts.push("## Structured Orchestration Contract");
+    parts.push("- Freeform prose is not enough for TeamClaw scheduling decisions.");
+    parts.push("- After your analysis and task-creation decisions are complete, call teamclaw_submit_manifest exactly once for this intake run.");
+    parts.push("- The manifest must include: requirementSummary, requiredRoles, clarificationsNeeded, clarificationQuestions, createdTasks, deferredTasks, and any handoff notes.");
+    parts.push("- Use createdTasks for execution-ready tasks that this run activated now, including a deliberately reused existing TeamClaw task when you chose not to duplicate it.");
+    parts.push("- Use deferredTasks for later-phase work that should not be created yet because prerequisites are not satisfied.");
+    parts.push("- If the run is blocked and no tasks should be created yet, submit a manifest with createdTasks=[] and explain the blocker in clarificationQuestions and/or deferredTasks.");
+    parts.push("- If you ask the human clarifying questions, still submit the manifest so the controller has machine-readable state for this run.");
+
     parts.push("");
     parts.push("## Requirement Intake Rules");
     parts.push("- Human messages are the initial requirement, not an already-decomposed task tree.");
@@ -111,6 +138,14 @@ export function createControllerPromptInjector(deps: ControllerPromptDeps) {
     parts.push("- Do not let a worker task turn itself into a controller/coordinator workflow.");
     parts.push("- If the correct role is busy, prefer waiting, messaging, or explicit reassignment over routing core work to an unrelated role.");
     parts.push("- If a task is blocked by missing information, keep it in the clarification queue until the human answers; do not guess on the user's behalf.");
+    parts.push("- You are never a substitute worker. Do not personally perform architecture, implementation, QA, release, infra, design, marketing, research, or other specialist work.");
+    parts.push("- Your own reply must stay at the orchestration layer: clarification, role selection, task decomposition, assignment decisions, and concise status updates.");
+    parts.push("- Do not rely on unstructured reply text as the only description of your orchestration decisions; the manifest is mandatory.");
+    if (hasOnDemandWorkerProvisioning(deps.config)) {
+      parts.push("- If no workers are currently registered but on-demand provisioning is enabled, you may still create execution-ready tasks so the required roles can be provisioned.");
+    } else {
+      parts.push("- If no workers are registered, you may mention which roles would be needed, but stop there and report the worker-capacity block to the human.");
+    }
     parts.push("- Use the controller itself for requirement analysis; use the PM role only for PM-owned deliverables after intake is clear.");
     parts.push(`- Use exact TeamClaw role IDs only: ${TEAMCLAW_ROLE_IDS_TEXT}.`);
 

package/src/controller/worker-provisioning.ts

@@ -6,6 +6,7 @@ import path from "node:path";
 import readline from "node:readline";
 import { createHash } from "node:crypto";
 import { spawn, type ChildProcess } from "node:child_process";
+import { fileURLToPath } from "node:url";
 import JSON5 from "json5";
 import type { PluginLogger } from "../../api.js";
 import { generateId } from "../protocol.js";
@@ -28,10 +29,11 @@ import type {
 
 const DEFAULT_CONTAINER_WORKER_PORT = 9527;
 const DEFAULT_CONTAINER_GATEWAY_PORT = 18789;
+const DEFAULT_DOCKER_BUNDLED_TEAMCLAW_PLUGIN_DIR = "/app/extensions/teamclaw";
 const PROVISIONING_RECORD_RETENTION_MS = 6 * 60 * 60 * 1000;
 const PROVISIONING_FAILURE_COOLDOWN_MS = 30_000;
 const PROCESS_TERMINATION_TIMEOUT_MS = 10_000;
-const DOCKER_API_VERSION = "v1.41";
+const DOCKER_API_VERSION = resolveDockerApiVersion();
 
 export type WorkerProvisioningManagerDeps = {
   config: PluginConfig;
@@ -258,10 +260,18 @@ export class WorkerProvisioningManager {
       return;
     }
 
-    const roles = this.getProvisionableRoles();
+    const roles = this.getProvisionableRoles(state);
     for (const role of roles) {
       const demand = this.computeRoleDemand(state, role);
       if (demand > 0) {
+        if (
+          this.deps.config.workerProvisioningRoles.length > 0 &&
+          !this.deps.config.workerProvisioningRoles.includes(role)
+        ) {
+          this.deps.logger.info(
+            `Provisioner: allowing role ${role} because pending task demand exists outside configured workerProvisioningRoles`,
+          );
+        }
         this.deps.logger.info(`Provisioner: role ${role} needs ${demand} additional worker(s) (${reason})`);
       }
       for (let i = 0; i < demand; i += 1) {
@@ -301,7 +311,7 @@ export class WorkerProvisioningManager {
       return;
     }
 
-    const roles = this.getProvisionableRoles();
+    const roles = this.getProvisionableRoles(state);
     for (const role of roles) {
       const activeWorkers = Object.values(state.workers).filter(
         (worker) => worker.role === role && worker.status !== "offline",
@@ -353,10 +363,14 @@ export class WorkerProvisioningManager {
     const workerId = `provisioned-${role}-${generateId()}`;
     const launchToken = `${generateId()}-${generateId()}`;
     const controllerUrl = this.resolveControllerUrl();
-    const workerPort = this.backend.type === "process"
+    const requiresDedicatedHostPorts = requiresDedicatedHostPortsForProvisioner(
+      this.backend.type,
+      this.deps.config,
+    );
+    const workerPort = requiresDedicatedHostPorts
       ? await reserveEphemeralPort()
       : DEFAULT_CONTAINER_WORKER_PORT;
-    const gatewayPort = this.backend.type === "process"
+    const gatewayPort = requiresDedicatedHostPorts
       ? await reserveEphemeralPort()
       : DEFAULT_CONTAINER_GATEWAY_PORT;
     const now = Date.now();
@@ -390,7 +404,7 @@ export class WorkerProvisioningManager {
         workerPort,
         gatewayPort,
         workspaceDir: getConfiguredWorkerWorkspaceDir(workerConfig),
-        env: this.buildForwardedEnv(),
+        env: this.buildForwardedEnv(controllerUrl),
         configJson: `${JSON.stringify(workerConfig, null, 2)}\n`,
       });
 
@@ -473,10 +487,35 @@ export class WorkerProvisioningManager {
     });
   }
 
-  private getProvisionableRoles(): RoleId[] {
-    return this.deps.config.workerProvisioningRoles.length > 0
-      ? this.deps.config.workerProvisioningRoles
-      : ROLES.map((role) => role.id);
+  private getProvisionableRoles(state: TeamState | null): RoleId[] {
+    const roleIds = new Set<RoleId>(
+      this.deps.config.workerProvisioningRoles.length > 0
+        ? this.deps.config.workerProvisioningRoles
+        : ROLES.map((role) => role.id),
+    );
+
+    if (!state) {
+      return [...roleIds];
+    }
+
+    for (const task of Object.values(state.tasks)) {
+      if (task.status !== "pending" && task.status !== "assigned") {
+        continue;
+      }
+      const taskRole = this.inferTaskRole(task);
+      if (taskRole) {
+        roleIds.add(taskRole);
+      }
+    }
+
+    for (const worker of Object.values(state.workers)) {
+      roleIds.add(worker.role);
+    }
+    for (const record of Object.values(state.provisioning?.workers ?? {})) {
+      roleIds.add(record.role);
+    }
+
+    return [...roleIds];
   }
 
   private countPendingTasksForRole(state: TeamState, role: RoleId): number {
@@ -493,6 +532,9 @@ export class WorkerProvisioningManager {
         return false;
       }
     }
+    if (task.assignedRole) {
+      return task.assignedRole === role;
+    }
     return this.inferTaskRole(task) === role;
   }
 
@@ -557,7 +599,7 @@ export class WorkerProvisioningManager {
     );
   }
 
-  private buildForwardedEnv(): Record<string, string> {
+  private buildForwardedEnv(controllerUrl: string): Record<string, string> {
     const env: Record<string, string> = {
       ...this.deps.config.workerProvisioningExtraEnv,
     };
@@ -567,7 +609,7 @@ export class WorkerProvisioningManager {
         env[name] = value;
       }
     }
-    return env;
+    return appendNoProxyEntries(env, controllerUrl);
   }
 
   private async loadBaseOpenClawConfig(): Promise<Record<string, unknown>> {
@@ -636,6 +678,7 @@ class ProcessProvisioner implements WorkerProvisionerBackend {
     const stateDir = path.join(runtimeHomeDir, ".openclaw");
     const configPath = path.join(stateDir, "openclaw.json");
     await fs.mkdir(stateDir, { recursive: true });
+    await prepareProcessRuntimeExtensions(stateDir);
     await fs.writeFile(configPath, spec.configJson, "utf8");
 
     const gatewayEntrypoint = resolveGatewayEntrypoint();
@@ -943,7 +986,8 @@ class DockerApiClient {
     okStatuses: number[],
   ): Promise<{ status: number; body: string }> {
     const payload = body === undefined ? undefined : JSON.stringify(body);
-    const finalPath = `/${DOCKER_API_VERSION}${requestPath}`;
+    // Prefer the daemon's negotiated default unless the operator pins a version explicitly.
+    const finalPath = DOCKER_API_VERSION ? `/${DOCKER_API_VERSION}${requestPath}` : requestPath;
 
     return await new Promise<{ status: number; body: string }>((resolve, reject) => {
       const transport = this.endpoint.protocol === "https:" ? https : http;
@@ -989,6 +1033,14 @@ type DockerEndpoint = {
   port?: number;
 };
 
+function resolveDockerApiVersion(): string | null {
+  const configured = process.env.DOCKER_API_VERSION?.trim();
+  if (!configured) {
+    return null;
+  }
+  return configured.startsWith("v") ? configured : `v${configured}`;
+}
+
 function createProvisionerBackend(
   config: PluginConfig,
   logger: PluginLogger,
@@ -1018,6 +1070,7 @@ function buildProvisionedWorkerConfig(
   },
 ): Record<string, unknown> {
   const config = cloneJson(baseConfig);
+  delete config.channels;
   const agents = ensureRecord(config.agents);
   const agentDefaults = ensureRecord(agents.defaults);
   delete agentDefaults.repoRoot;
@@ -1033,10 +1086,14 @@ function buildProvisionedWorkerConfig(
   gateway.mode = "local";
   gateway.bind = "loopback";
   gateway.port = spec.gatewayPort;
+  delete gateway.remote;
   config.gateway = gateway;
 
   const plugins = ensureRecord(config.plugins);
   plugins.enabled = true;
+  if (controllerConfig.workerProvisioningType === "docker" || controllerConfig.workerProvisioningType === "kubernetes") {
+    delete plugins.load;
+  }
   const entries = ensureRecord(plugins.entries);
   const teamclawEntry = ensureRecord(entries.teamclaw);
   teamclawEntry.enabled = true;
@@ -1097,10 +1154,104 @@ async function loadOpenClawConfig(configPath: string): Promise<Record<string, un
   return parseLooseJsonObject(raw, configPath);
 }
 
+async function prepareProcessRuntimeExtensions(stateDir: string): Promise<void> {
+  const runtimeExtensionsDir = path.join(stateDir, "extensions");
+  const controllerExtensionsDir = path.join(path.dirname(resolveDefaultOpenClawConfigPath()), "extensions");
+  if (await pathExists(controllerExtensionsDir)) {
+    await fs.symlink(controllerExtensionsDir, runtimeExtensionsDir, "dir");
+    return;
+  }
+
+  await fs.mkdir(runtimeExtensionsDir, { recursive: true });
+  await fs.symlink(resolveCurrentTeamClawPluginRootDir(), path.join(runtimeExtensionsDir, "teamclaw"), "dir");
+}
+
 function cloneJson<T>(value: T): T {
   return JSON.parse(JSON.stringify(value)) as T;
 }
 
+function requiresDedicatedHostPortsForProvisioner(
+  provider: WorkerProvisioningType,
+  config: PluginConfig,
+): boolean {
+  if (provider === "process") {
+    return true;
+  }
+  return provider === "docker" && isDockerHostNetwork(config.workerProvisioningDockerNetwork);
+}
+
+function isDockerHostNetwork(networkMode: string): boolean {
+  return networkMode.trim().toLowerCase() === "host";
+}
+
+function extractDockerBindTarget(bind: string): string | null {
+  for (const part of bind.split(":").reverse()) {
+    const trimmed = part.trim();
+    if (trimmed.startsWith("/")) {
+      return trimmed;
+    }
+  }
+  return null;
+}
+
+function appendNoProxyEntries(env: Record<string, string>, controllerUrl: string): Record<string, string> {
+  const requiredEntries = resolveRequiredNoProxyEntries(controllerUrl);
+  if (requiredEntries.length === 0) {
+    return env;
+  }
+
+  const upperBase = env.NO_PROXY ?? process.env.NO_PROXY ?? process.env.no_proxy ?? "";
+  const lowerBase = env.no_proxy ?? process.env.no_proxy ?? env.NO_PROXY ?? process.env.NO_PROXY ?? "";
+
+  env.NO_PROXY = mergeNoProxyEntries(upperBase, requiredEntries);
+  env.no_proxy = mergeNoProxyEntries(lowerBase, requiredEntries);
+  return env;
+}
+
+function resolveRequiredNoProxyEntries(controllerUrl: string): string[] {
+  const required = new Set<string>(["localhost", "127.0.0.1", "::1", "[::1]"]);
+  try {
+    const host = new URL(controllerUrl).hostname.trim();
+    if (host) {
+      required.add(host);
+    }
+  } catch {
+    // Ignore malformed controller URLs; worker registration will fail separately.
+  }
+  return Array.from(required);
+}
+
+function mergeNoProxyEntries(existing: string, requiredEntries: string[]): string {
+  const tokens = new Map<string, string>();
+  for (const entry of existing.split(",")) {
+    const trimmed = entry.trim();
+    if (!trimmed) {
+      continue;
+    }
+    tokens.set(trimmed.toLowerCase(), trimmed);
+  }
+  for (const entry of requiredEntries) {
+    const trimmed = entry.trim();
+    if (!trimmed) {
+      continue;
+    }
+    tokens.set(trimmed.toLowerCase(), trimmed);
+  }
+  return Array.from(tokens.values()).join(",");
+}
+
+async function pathExists(targetPath: string): Promise<boolean> {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return false;
+    }
+    throw err;
+  }
+}
+
 function ensureRecord(value: unknown): Record<string, unknown> {
   return value && typeof value === "object" && !Array.isArray(value)
     ? { ...(value as Record<string, unknown>) }
@@ -1147,6 +1298,10 @@ function resolveGatewayEntrypoint(): string {
   return path.resolve(scriptPath);
 }
 
+function resolveCurrentTeamClawPluginRootDir(): string {
+  return path.resolve(fileURLToPath(new URL("../../", import.meta.url)));
+}
+
 function attachChildLogs(child: ChildProcess, logger: PluginLogger, prefix: string): void {
   if (child.stdout) {
     const stdoutReader = readline.createInterface({ input: child.stdout });
@@ -1266,6 +1421,9 @@ function buildContainerBootstrapScript(): string {
 
 function buildDockerBinds(config: PluginConfig): string[] {
   const binds = [...config.workerProvisioningDockerMounts];
+  if (!binds.some((bind) => extractDockerBindTarget(bind) === DEFAULT_DOCKER_BUNDLED_TEAMCLAW_PLUGIN_DIR)) {
+    binds.unshift(`${resolveCurrentTeamClawPluginRootDir()}:${DEFAULT_DOCKER_BUNDLED_TEAMCLAW_PLUGIN_DIR}:ro`);
+  }
   if (config.workerProvisioningDockerWorkspaceVolume && config.workerProvisioningWorkspaceRoot) {
     binds.unshift(`${config.workerProvisioningDockerWorkspaceVolume}:${config.workerProvisioningWorkspaceRoot}`);
   }

package/src/git-collaboration.ts

@@ -9,11 +9,13 @@ import { resolveDefaultOpenClawWorkspaceDir } from "./openclaw-workspace.js";
 const TEAMCLAW_IMPORT_REF_PREFIX = "refs/teamclaw/imports";
 const TEAMCLAW_RUNTIME_EXCLUDES = [
   ".openclaw/",
+  ".clawhub/",
   "AGENTS.md",
   "BOOTSTRAP.md",
   "HEARTBEAT.md",
   "IDENTITY.md",
   "SOUL.md",
+  "skills/",
   "TOOLS.md",
   "USER.md",
 ];