@teamclaws/teamclaw 2026.3.21

package/src/worker/worker-service.ts

@@ -0,0 +1,194 @@
+import http from "node:http";
+import type { OpenClawPluginService, OpenClawPluginServiceContext, PluginLogger } from "../../api.js";
+import type { PluginConfig, TaskAssignmentPayload, WorkerIdentity } from "../types.js";
+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";
+
+export type WorkerServiceDeps = {
+  config: PluginConfig;
+  logger: PluginLogger;
+  onIdentityEstablished: (identity: WorkerIdentity) => void;
+  taskExecutor?: (taskDescription: string, taskId: string) => Promise<string>;
+  prepareTaskAssignment?: (assignment: TaskAssignmentPayload) => Promise<void> | void;
+  publishTaskAssignment?: (assignment: TaskAssignmentPayload, result: string) => Promise<void> | void;
+  cancelTaskExecution?: (taskId: string) => Promise<boolean> | boolean;
+  messageQueue?: MessageQueue;
+};
+
+export function createWorkerService(deps: WorkerServiceDeps): OpenClawPluginService {
+  const { config, logger, onIdentityEstablished, taskExecutor: externalTaskExecutor } = deps;
+  let identityManager: IdentityManager;
+  let messageQueue: MessageQueue;
+  let server: http.Server | null = null;
+  let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  let controllerUrl: string | null = null;
+  let workerId: string | null = null;
+  let activeTaskId: string | undefined;
+  const cancelledTaskIds = new Set<string>();
+
+  const taskExecutor = externalTaskExecutor
+    ? async (assignment: TaskAssignmentPayload): Promise<string> => {
+        const taskId = assignment.taskId;
+        cancelledTaskIds.delete(taskId);
+        activeTaskId = taskId;
+        try {
+          await deps.prepareTaskAssignment?.(assignment);
+          const taskPrompt = [assignment.title.trim(), assignment.description.trim()].filter(Boolean).join("\n\n");
+          const result = await externalTaskExecutor(taskPrompt, taskId);
+          if (cancelledTaskIds.has(taskId)) {
+            throw new Error("Task execution cancelled by controller");
+          }
+          await deps.publishTaskAssignment?.(assignment, result);
+          return result;
+        } finally {
+          activeTaskId = undefined;
+          if (!cancelledTaskIds.has(taskId)) {
+            cancelledTaskIds.delete(taskId);
+          }
+        }
+      }
+    : undefined;
+
+  function reportTaskResult(taskId: string, result: string, error: string | null): void {
+    if (cancelledTaskIds.has(taskId)) {
+      logger.info(`Worker: suppressing result report for cancelled task ${taskId}`);
+      return;
+    }
+    if (!controllerUrl) return;
+    fetch(`${controllerUrl}/api/v1/tasks/${taskId}/result`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ result, error, workerId }),
+    }).catch((err) => {
+      logger.error(`Worker: failed to report task result: ${String(err)}`);
+    });
+  }
+
+  async function cancelAssignedTask(taskId: string): Promise<boolean> {
+    if (activeTaskId !== taskId) {
+      return false;
+    }
+
+    cancelledTaskIds.add(taskId);
+    try {
+      const cancelled = await deps.cancelTaskExecution?.(taskId);
+      return cancelled ?? true;
+    } catch (err) {
+      logger.warn(`Worker: failed to cancel task ${taskId}: ${err instanceof Error ? err.message : String(err)}`);
+      return true;
+    }
+  }
+
+  function isTaskCancelled(taskId: string): boolean {
+    return cancelledTaskIds.has(taskId);
+  }
+
+  async function startServer(): Promise<void> {
+    const handler = createWorkerHttpHandler(
+        { role: config.role, port: config.port },
+        logger,
+        messageQueue,
+        workerId ?? "",
+        taskExecutor,
+        reportTaskResult,
+        cancelAssignedTask,
+        isTaskCancelled,
+      );
+
+    if (server) {
+      await new Promise<void>((resolve) => server!.close(() => resolve()));
+    }
+
+    server = http.createServer(handler);
+    await new Promise<void>((resolve, reject) => {
+      server!.listen(config.port, () => {
+        logger.info(`Worker: HTTP server listening on port ${config.port}`);
+        resolve();
+      });
+      server!.on("error", reject);
+    });
+  }
+
+  return {
+    id: "teamclaw-worker",
+    async start(_ctx: OpenClawPluginServiceContext) {
+      await ensureOpenClawWorkspaceMemoryDir(logger);
+
+      messageQueue = deps.messageQueue ?? new MessageQueue();
+      identityManager = new IdentityManager(config, logger);
+
+      // Start HTTP server initially (without identity)
+      await startServer();
+
+      // Register with controller
+      const identity = await identityManager.register();
+      if (!identity) {
+        logger.warn("Worker: could not register with controller, will retry on next heartbeat");
+      } else {
+        controllerUrl = identity.controllerUrl;
+        workerId = identity.workerId;
+        // Restart server with worker ID and task executor
+        await startServer();
+        onIdentityEstablished(identity);
+      }
+
+      // Start heartbeat
+      heartbeatTimer = setInterval(async () => {
+        if (!identityManager.hasIdentity()) {
+          const newIdentity = await identityManager.register();
+          if (newIdentity && !controllerUrl) {
+            controllerUrl = newIdentity.controllerUrl;
+            workerId = newIdentity.workerId;
+            await startServer();
+            onIdentityEstablished(newIdentity);
+          }
+          return;
+        }
+
+        const id = identityManager.getIdentity();
+        if (!id || !controllerUrl) return;
+
+        try {
+          const heartbeat = createHeartbeatPayload(
+            id.workerId,
+            activeTaskId ? "busy" : "idle",
+            activeTaskId,
+          );
+          const res = await fetch(`${controllerUrl}/api/v1/workers/${id.workerId}/heartbeat`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(heartbeat),
+          });
+
+          if (!res.ok) {
+            logger.warn(`Worker: heartbeat failed (${res.status})`);
+          }
+        } catch (err) {
+          logger.warn(`Worker: heartbeat error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+      }, config.heartbeatIntervalMs);
+
+      if (heartbeatTimer) {
+        const timer = heartbeatTimer as unknown as { unref?: () => void };
+        timer.unref?.();
+      }
+    },
+    async stop() {
+      if (heartbeatTimer) {
+        clearInterval(heartbeatTimer);
+        heartbeatTimer = null;
+      }
+      if (server) {
+        await new Promise<void>((resolve) => server!.close(() => resolve()));
+        server = null;
+      }
+      if (identityManager) {
+        await identityManager.clear();
+      }
+      logger.info("Worker: stopped");
+    },
+  };
+}

package/src/workspace-browser.ts

@@ -0,0 +1,312 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveDefaultOpenClawWorkspaceDir } from "./openclaw-workspace.js";
+
+const MAX_PREVIEW_BYTES = 256 * 1024;
+const MAX_TREE_DEPTH = 8;
+const HIDDEN_WORKSPACE_NAMES = new Set([
+  ".git",
+  ".openclaw",
+  "node_modules",
+  "memory",
+  "AGENTS.md",
+  "BOOTSTRAP.md",
+  "HEARTBEAT.md",
+  "IDENTITY.md",
+  "SOUL.md",
+  "TOOLS.md",
+  "USER.md",
+]);
+const MARKDOWN_EXTENSIONS = new Set([".md", ".markdown", ".mdown"]);
+const HTML_EXTENSIONS = new Set([".html", ".htm"]);
+const TEXT_EXTENSIONS = new Set([
+  ".txt",
+  ".js",
+  ".mjs",
+  ".cjs",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".css",
+  ".scss",
+  ".sass",
+  ".less",
+  ".json",
+  ".yml",
+  ".yaml",
+  ".xml",
+  ".svg",
+  ".sh",
+  ".bash",
+  ".zsh",
+  ".py",
+  ".go",
+  ".rs",
+  ".java",
+  ".kt",
+  ".swift",
+  ".rb",
+  ".php",
+  ".sql",
+  ".env",
+  ".gitignore",
+  ".gitattributes",
+  ".npmrc",
+  ".editorconfig",
+]);
+
+export type WorkspaceTreeNode = {
+  name: string;
+  path: string;
+  type: "directory" | "file";
+  size?: number;
+  previewType?: "source" | "markdown" | "html" | "binary";
+  children?: WorkspaceTreeNode[];
+};
+
+export type WorkspaceTreePayload = {
+  root: string;
+  entries: WorkspaceTreeNode[];
+};
+
+export type WorkspaceFilePayload = {
+  name: string;
+  path: string;
+  size: number;
+  extension: string;
+  previewType: "source" | "markdown" | "html" | "binary";
+  truncated: boolean;
+  content?: string;
+  rawUrl: string;
+  contentType: string;
+};
+
+export async function listWorkspaceTree(): Promise<WorkspaceTreePayload> {
+  const workspaceDir = await ensureWorkspaceDir();
+  const entries = await readTree(workspaceDir, "", 0);
+  return {
+    root: "/",
+    entries,
+  };
+}
+
+export async function readWorkspaceFile(relativePath: string): Promise<WorkspaceFilePayload> {
+  const { normalizedPath, absolutePath } = await resolveWorkspacePath(relativePath);
+  const stat = await fs.stat(absolutePath);
+  if (!stat.isFile()) {
+    throw new Error("Workspace path is not a file");
+  }
+
+  const extension = path.extname(normalizedPath).toLowerCase();
+  const contentType = getContentType(normalizedPath);
+  const handle = await fs.open(absolutePath, "r");
+  try {
+    const length = Math.min(stat.size, MAX_PREVIEW_BYTES + 1);
+    const buffer = Buffer.alloc(length);
+    const { bytesRead } = await handle.read(buffer, 0, length, 0);
+    const slice = buffer.subarray(0, bytesRead);
+    const truncated = stat.size > MAX_PREVIEW_BYTES;
+    const previewType = detectPreviewType(normalizedPath, slice);
+
+    return {
+      name: path.basename(normalizedPath),
+      path: normalizedPath,
+      size: stat.size,
+      extension,
+      previewType,
+      truncated,
+      content: previewType === "binary" ? undefined : slice.subarray(0, Math.min(slice.length, MAX_PREVIEW_BYTES)).toString("utf8"),
+      rawUrl: buildWorkspaceRawUrl(normalizedPath),
+      contentType,
+    };
+  } finally {
+    await handle.close();
+  }
+}
+
+export async function readWorkspaceRawFile(relativePath: string): Promise<{
+  content: Buffer;
+  contentType: string;
+}> {
+  const { absolutePath } = await resolveWorkspacePath(relativePath);
+  const stat = await fs.stat(absolutePath);
+  if (!stat.isFile()) {
+    throw new Error("Workspace path is not a file");
+  }
+
+  return {
+    content: await fs.readFile(absolutePath),
+    contentType: getContentType(absolutePath),
+  };
+}
+
+export function buildWorkspaceRawUrl(relativePath: string): string {
+  const normalizedPath = normalizeWorkspacePath(relativePath);
+  const encodedPath = normalizedPath.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+  return `/api/v1/workspace/raw/${encodedPath}`;
+}
+
+async function ensureWorkspaceDir(): Promise<string> {
+  const workspaceDir = resolveDefaultOpenClawWorkspaceDir();
+  await fs.mkdir(workspaceDir, { recursive: true });
+  return workspaceDir;
+}
+
+async function resolveWorkspacePath(relativePath: string): Promise<{
+  workspaceDir: string;
+  normalizedPath: string;
+  absolutePath: string;
+}> {
+  const workspaceDir = await ensureWorkspaceDir();
+  const normalizedPath = normalizeWorkspacePath(relativePath);
+  if (!normalizedPath) {
+    throw new Error("workspace path is required");
+  }
+
+  const absolutePath = path.resolve(workspaceDir, normalizedPath);
+  const relativeFromWorkspace = path.relative(workspaceDir, absolutePath).replace(/\\/g, "/");
+  if (!relativeFromWorkspace || relativeFromWorkspace.startsWith("..") || path.isAbsolute(relativeFromWorkspace)) {
+    throw new Error("workspace path must stay inside the workspace");
+  }
+
+  return {
+    workspaceDir,
+    normalizedPath: relativeFromWorkspace,
+    absolutePath,
+  };
+}
+
+function normalizeWorkspacePath(relativePath: string): string {
+  const value = String(relativePath || "").trim().replace(/\\/g, "/").replace(/^\/+/, "");
+  if (!value) {
+    return "";
+  }
+
+  const normalized = path.posix.normalize(value);
+  if (normalized === "." || normalized === ".." || normalized.startsWith("../")) {
+    throw new Error("Invalid workspace path");
+  }
+  return normalized;
+}
+
+async function readTree(dirPath: string, relativeDir: string, depth: number): Promise<WorkspaceTreeNode[]> {
+  if (depth > MAX_TREE_DEPTH) {
+    return [];
+  }
+
+  const dirents = await fs.readdir(dirPath, { withFileTypes: true });
+  const visibleDirents = dirents
+    .filter((dirent) => !HIDDEN_WORKSPACE_NAMES.has(dirent.name))
+    .sort((left, right) => {
+      if (left.isDirectory() && !right.isDirectory()) return -1;
+      if (!left.isDirectory() && right.isDirectory()) return 1;
+      return left.name.localeCompare(right.name);
+    });
+
+  const nodes: WorkspaceTreeNode[] = [];
+  for (const dirent of visibleDirents) {
+    const childRelativePath = relativeDir ? `${relativeDir}/${dirent.name}` : dirent.name;
+    const childAbsolutePath = path.join(dirPath, dirent.name);
+
+    if (dirent.isDirectory()) {
+      nodes.push({
+        name: dirent.name,
+        path: childRelativePath,
+        type: "directory",
+        children: await readTree(childAbsolutePath, childRelativePath, depth + 1),
+      });
+      continue;
+    }
+
+    if (!dirent.isFile()) {
+      continue;
+    }
+
+    const stat = await fs.stat(childAbsolutePath);
+    nodes.push({
+      name: dirent.name,
+      path: childRelativePath,
+      type: "file",
+      size: stat.size,
+      previewType: classifyPreviewType(childRelativePath),
+    });
+  }
+
+  return nodes;
+}
+
+function classifyPreviewType(filePath: string): "source" | "markdown" | "html" | "binary" {
+  const extension = path.extname(filePath).toLowerCase();
+  if (MARKDOWN_EXTENSIONS.has(extension)) {
+    return "markdown";
+  }
+  if (HTML_EXTENSIONS.has(extension)) {
+    return "html";
+  }
+  return TEXT_EXTENSIONS.has(extension) ? "source" : "binary";
+}
+
+function detectPreviewType(filePath: string, content: Buffer): "source" | "markdown" | "html" | "binary" {
+  const classified = classifyPreviewType(filePath);
+  if (classified === "markdown" || classified === "html") {
+    return classified;
+  }
+  if (classified === "source") {
+    return "source";
+  }
+  return isLikelyBinary(content) ? "binary" : "source";
+}
+
+function isLikelyBinary(content: Buffer): boolean {
+  const sample = content.subarray(0, Math.min(content.length, 4096));
+  for (const byte of sample) {
+    if (byte === 0) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function getContentType(filePath: string): string {
+  const extension = path.extname(filePath).toLowerCase();
+  switch (extension) {
+    case ".html":
+    case ".htm":
+      return "text/html; charset=utf-8";
+    case ".md":
+    case ".markdown":
+    case ".mdown":
+      return "text/markdown; charset=utf-8";
+    case ".css":
+      return "text/css; charset=utf-8";
+    case ".js":
+    case ".mjs":
+    case ".cjs":
+      return "application/javascript; charset=utf-8";
+    case ".json":
+      return "application/json; charset=utf-8";
+    case ".svg":
+      return "image/svg+xml";
+    case ".txt":
+    case ".sh":
+    case ".bash":
+    case ".zsh":
+    case ".yml":
+    case ".yaml":
+    case ".ts":
+    case ".tsx":
+    case ".jsx":
+    case ".py":
+    case ".go":
+    case ".rs":
+    case ".java":
+    case ".kt":
+    case ".swift":
+    case ".rb":
+    case ".php":
+    case ".sql":
+      return "text/plain; charset=utf-8";
+    default:
+      return "application/octet-stream";
+  }
+}

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "allowImportingTsExtensions": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "lib": ["DOM", "DOM.Iterable", "ES2023"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "es2023",
+    "paths": {
+      "openclaw/plugin-sdk": ["../openclaw/src/plugin-sdk/index.ts"],
+      "openclaw/plugin-sdk/*": ["../openclaw/src/plugin-sdk/*"]
+    }
+  },
+  "include": ["./**/*.ts", "./*.ts"],
+  "exclude": ["node_modules", "dist"]
+}