@lobu/worker 6.1.1 → 7.1.0

package/src/gateway/types.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared types for gateway communication
+ */
+
+import type { AgentOptions, ThreadResponsePayload } from "@lobu/core";
+
+/**
+ * Platform-specific metadata (e.g., Slack team_id, channel, thread_ts)
+ */
+interface PlatformMetadata {
+  team_id?: string;
+  channel?: string;
+  ts?: string;
+  thread_ts?: string;
+  files?: unknown[];
+  traceId?: string; // Trace ID for end-to-end observability
+  [key: string]: unknown;
+}
+
+/**
+ * Job type for queue messages
+ * - message: Standard agent message execution
+ * - exec: Direct command execution in sandbox
+ */
+export type JobType = "message" | "exec";
+
+/**
+ * Message payload for agent execution
+ */
+export interface MessagePayload {
+  botId: string;
+  userId: string;
+  agentId: string;
+  conversationId: string;
+  platform: string;
+  channelId: string;
+  messageId: string;
+  messageText: string;
+  platformMetadata: PlatformMetadata;
+  agentOptions: AgentOptions;
+  jobId?: string; // Optional job ID from gateway
+  teamId?: string; // Optional team ID (WhatsApp uses top-level, Slack uses platformMetadata)
+
+  // Job type (default: "message")
+  jobType?: JobType;
+
+  // Exec-specific fields (only used when jobType === "exec")
+  execId?: string; // Unique ID for exec job (for response routing)
+  execCommand?: string; // Command to execute
+  execCwd?: string; // Working directory for command
+  execEnv?: Record<string, string>; // Additional environment variables
+  execTimeout?: number; // Timeout in milliseconds
+}
+
+/**
+ * Queued message with timestamp
+ */
+export interface QueuedMessage {
+  payload: MessagePayload;
+  timestamp: number;
+}
+
+/**
+ * Response data sent back to gateway
+ */
+export type ResponseData = ThreadResponsePayload & {
+  originalMessageId: string;
+};

package/src/index.ts

@@ -0,0 +1,123 @@
+#!/usr/bin/env bun
+
+import {
+  createLogger,
+  initSentry,
+  initTracing,
+  moduleRegistry,
+} from "@lobu/core";
+
+const logger = createLogger("worker");
+
+import { GatewayClient } from "./gateway/sse-client";
+import { startWorkerHttpServer, stopWorkerHttpServer } from "./server";
+
+/**
+ * Main entry point for gateway-based persistent worker
+ */
+async function main() {
+  process.on("unhandledRejection", (reason) => {
+    logger.error("Unhandled rejection:", reason);
+    process.exit(1);
+  });
+
+  process.on("uncaughtException", (error) => {
+    logger.error("Uncaught exception:", error);
+    process.exit(1);
+  });
+
+  logger.info("Starting worker...");
+
+  await initSentry();
+
+  const otlpEndpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+  if (otlpEndpoint) {
+    initTracing({
+      serviceName: "lobu-worker",
+      otlpEndpoint,
+    });
+    logger.info(`Tracing initialized: lobu-worker -> ${otlpEndpoint}`);
+  }
+
+  await moduleRegistry.registerAvailableModules();
+  await moduleRegistry.initAll();
+  logger.info("✅ Modules initialized");
+
+  logger.info("🔄 Starting in gateway mode (SSE/HTTP-based persistent worker)");
+
+  const userId = process.env.USER_ID;
+
+  if (!userId) {
+    logger.error(
+      "❌ USER_ID environment variable is required for gateway mode"
+    );
+    process.exit(1);
+  }
+
+  try {
+    const deploymentName = process.env.DEPLOYMENT_NAME;
+    const dispatcherUrl = process.env.DISPATCHER_URL;
+    const workerToken = process.env.WORKER_TOKEN;
+
+    if (!deploymentName) {
+      logger.error("❌ DEPLOYMENT_NAME environment variable is required");
+      process.exit(1);
+    }
+    if (!dispatcherUrl) {
+      logger.error("❌ DISPATCHER_URL environment variable is required");
+      process.exit(1);
+    }
+    if (!workerToken) {
+      logger.error("❌ WORKER_TOKEN environment variable is required");
+      process.exit(1);
+    }
+
+    const httpPort = await startWorkerHttpServer();
+    logger.info(`Worker HTTP server started on port ${httpPort}`);
+
+    logger.info(`🚀 Starting Gateway-based Persistent Worker`);
+    logger.info(`- User ID: ${userId}`);
+    logger.info(`- Deployment: ${deploymentName}`);
+    logger.info(`- Dispatcher URL: ${dispatcherUrl}`);
+
+    const gatewayClient = new GatewayClient(
+      dispatcherUrl,
+      workerToken,
+      userId,
+      deploymentName,
+      httpPort
+    );
+
+    // Register signal handlers before async operations
+    let isShuttingDown = false;
+    const shutdown = async (signal: NodeJS.Signals) => {
+      if (isShuttingDown) return;
+      isShuttingDown = true;
+      logger.info(`Received ${signal}, shutting down gateway worker...`);
+      await gatewayClient.stop();
+      await stopWorkerHttpServer();
+      process.exit(0);
+    };
+
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+    process.on("SIGINT", () => shutdown("SIGINT"));
+
+    logger.info("🔌 Connecting to dispatcher...");
+    await gatewayClient.start();
+    logger.info("✅ Gateway worker started successfully");
+
+    await new Promise<never>(() => {
+      // Intentionally never resolves — block process until signal.
+    });
+  } catch (error) {
+    logger.error("❌ Gateway worker failed:", error);
+    process.exit(1);
+  }
+}
+
+export type { WorkerConfig } from "./core/types";
+
+main().catch((error) => {
+  logger.error("Fatal error in main:", error);
+  process.exit(1);
+});

package/src/instructions/builder.ts

@@ -0,0 +1,44 @@
+import {
+  createLogger,
+  type InstructionContext,
+  type InstructionProvider,
+} from "@lobu/core";
+
+const logger = createLogger("instruction-generator");
+
+/**
+ * Generate custom instructions using modular providers.
+ * Only generates worker-local instructions (core, projects) — platform and
+ * MCP instructions are provided by the gateway.
+ *
+ * Per-provider error handling lives on `BaseInstructionProvider` (a thrown
+ * provider returns `""`). The fallback below covers the unlikely case of a
+ * provider that bypasses the base class throwing during the loop itself.
+ */
+export async function generateCustomInstructions(
+  providers: InstructionProvider[],
+  context: InstructionContext
+): Promise<string> {
+  try {
+    const sorted = [...providers].sort((a, b) => a.priority - b.priority);
+    const sections: string[] = [];
+    for (const provider of sorted) {
+      const instructions = await provider.getInstructions(context);
+      if (instructions?.trim()) {
+        sections.push(instructions.trim());
+      }
+    }
+
+    const instructions = sections.join("\n\n");
+    logger.info(
+      `[WORKER-INSTRUCTIONS] Generated ${instructions.length} characters from ${providers.length} local providers`
+    );
+    logger.debug(`[WORKER-INSTRUCTIONS] \n${instructions}`);
+    return instructions;
+  } catch (error) {
+    logger.error("Failed to generate worker instructions:", error);
+    const fallback = `You are a helpful AI agent for user ${context.userId}.`;
+    logger.warn(`[WORKER-INSTRUCTIONS] Using fallback: ${fallback}`);
+    return fallback;
+  }
+}

package/src/instructions/providers.ts

@@ -0,0 +1,27 @@
+/**
+ * Instruction providers for worker
+ */
+
+import { BaseInstructionProvider, type InstructionContext } from "@lobu/core";
+
+/**
+ * Provides information about available projects in the workspace
+ */
+export class ProjectsInstructionProvider extends BaseInstructionProvider {
+  readonly name = "projects";
+  readonly priority = 30;
+
+  protected buildInstructions(context: InstructionContext): string {
+    if (!context.availableProjects || context.availableProjects.length === 0) {
+      return `**Available projects:**
+  - none`;
+    }
+
+    const projectList = context.availableProjects
+      .map((project: string) => `  - ${project}`)
+      .join("\n");
+
+    return `**Available projects:**
+${projectList}`;
+  }
+}

package/src/modules/lifecycle.ts

@@ -0,0 +1,92 @@
+import {
+  createLogger,
+  type ModuleSessionContext,
+  moduleRegistry,
+  type SessionContext,
+  type WorkerModule,
+} from "@lobu/core";
+
+const logger = createLogger("worker");
+
+/**
+ * Execute an operation on all worker modules with consistent error handling.
+ * Errors in individual modules are logged but do not halt iteration.
+ */
+async function executeForAllModules<T>(
+  operation: (module: WorkerModule) => Promise<T>,
+  operationName: string
+): Promise<T[]> {
+  const workerModules = moduleRegistry.getWorkerModules();
+  const results: T[] = [];
+  for (const module of workerModules) {
+    try {
+      results.push(await operation(module));
+    } catch (error) {
+      logger.error(
+        `Failed to execute ${operationName} for module ${module.name}:`,
+        error
+      );
+    }
+  }
+  return results;
+}
+
+export async function onSessionStart(
+  context: SessionContext
+): Promise<SessionContext> {
+  // Convert to module session context
+  const moduleContext: ModuleSessionContext = {
+    userId: context.userId,
+    conversationId: context.conversationId || "",
+    systemPrompt: context.customInstructions || "",
+    workspace: undefined,
+  };
+
+  let updatedContext = moduleContext;
+
+  await executeForAllModules(async (module) => {
+    updatedContext = await module.onSessionStart(updatedContext);
+  }, "onSessionStart");
+
+  // Merge back into original context, mapping systemPrompt back to customInstructions
+  return {
+    ...context,
+    customInstructions:
+      updatedContext.systemPrompt || context.customInstructions,
+  };
+}
+
+/**
+ * Configuration for module workspace initialization
+ */
+interface ModuleWorkspaceConfig {
+  workspaceDir: string;
+  username: string;
+  sessionKey: string;
+}
+
+export async function initModuleWorkspace(
+  config: ModuleWorkspaceConfig
+): Promise<void> {
+  await executeForAllModules(
+    (module) => module.initWorkspace(config),
+    "initWorkspace"
+  );
+}
+
+export async function collectModuleData(context: {
+  workspaceDir: string;
+  userId: string;
+  conversationId: string;
+}): Promise<Record<string, unknown>> {
+  const moduleData: Record<string, unknown> = {};
+
+  await executeForAllModules(async (module) => {
+    const data = await module.onBeforeResponse(context);
+    if (data !== null) {
+      moduleData[module.name] = data;
+    }
+  }, "onBeforeResponse");
+
+  return moduleData;
+}

package/src/openclaw/custom-tools.ts

@@ -0,0 +1,315 @@
+import { getCustomToolDescription, type McpToolDef } from "@lobu/core";
+import type { AgentToolResult } from "@mariozechner/pi-agent-core";
+import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
+import type { Static } from "@sinclair/typebox";
+import { type TSchema, Type } from "@sinclair/typebox";
+import type { GatewayParams, TextResult } from "../shared/tool-implementations";
+import {
+  askUserQuestion,
+  callMcpTool,
+  checkMcpLogin,
+  generateAudio,
+  generateImage,
+  getChannelHistory,
+  logoutMcp,
+  startMcpLogin,
+  uploadUserFile,
+} from "../shared/tool-implementations";
+
+type ToolResult = AgentToolResult<Record<string, unknown>>;
+
+/** Adapt shared TextResult to OpenClaw's ToolResult (adds details field) */
+function toToolResult(result: TextResult): ToolResult {
+  return { content: result.content, details: {} };
+}
+
+/**
+ * Create a ToolDefinition with proper type bridging between TypeBox schemas
+ * and the shared tool implementation functions. Eliminates per-tool `as` casts
+ * by casting once at the boundary.
+ */
+function defineTool<T extends TSchema>(config: {
+  name: string;
+  description: string;
+  parameters: T;
+  run: (args: Static<T>) => Promise<TextResult>;
+}): ToolDefinition {
+  return {
+    name: config.name,
+    label: config.name,
+    description: config.description,
+    parameters: config.parameters,
+    execute: async (_toolCallId, args) =>
+      toToolResult(await config.run(args as Static<T>)),
+  };
+}
+
+export function createOpenClawCustomTools(params: {
+  gatewayUrl: string;
+  workerToken: string;
+  channelId: string;
+  conversationId: string;
+  platform?: string;
+  /** Session workspace directory. Required — UploadUserFile resolves relative paths against it. */
+  workspaceDir: string;
+  onCustomEvent?: (
+    name: string,
+    data: Record<string, unknown>
+  ) => Promise<void> | void;
+}): ToolDefinition[] {
+  const gw: GatewayParams = {
+    gatewayUrl: params.gatewayUrl,
+    workerToken: params.workerToken,
+    channelId: params.channelId,
+    conversationId: params.conversationId,
+    platform: params.platform || "slack",
+    workspaceDir: params.workspaceDir,
+  };
+
+  const tools: ToolDefinition[] = [
+    defineTool({
+      name: "UploadUserFile",
+      description: getCustomToolDescription("UploadUserFile"),
+      parameters: Type.Object({
+        file_path: Type.String({
+          description:
+            "Path to the file to show (absolute or relative to workspace)",
+        }),
+        description: Type.Optional(
+          Type.String({
+            description:
+              "Optional description of what the file contains or shows",
+          })
+        ),
+      }),
+      run: (args) =>
+        uploadUserFile(gw, args, {
+          onUploaded: (data) => params.onCustomEvent?.("file-uploaded", data),
+        }),
+    }),
+
+    defineTool({
+      name: "GenerateImage",
+      description: getCustomToolDescription("GenerateImage"),
+      parameters: Type.Object({
+        prompt: Type.String({
+          description: "The image prompt to generate",
+        }),
+        size: Type.Optional(
+          Type.Union(
+            [
+              Type.Literal("1024x1024"),
+              Type.Literal("1024x1536"),
+              Type.Literal("1536x1024"),
+              Type.Literal("auto"),
+            ],
+            {
+              description: "Output image size (default: 1024x1024)",
+            }
+          )
+        ),
+        quality: Type.Optional(
+          Type.Union(
+            [
+              Type.Literal("low"),
+              Type.Literal("medium"),
+              Type.Literal("high"),
+              Type.Literal("auto"),
+            ],
+            {
+              description: "Image quality (default: auto)",
+            }
+          )
+        ),
+        background: Type.Optional(
+          Type.Union(
+            [
+              Type.Literal("transparent"),
+              Type.Literal("opaque"),
+              Type.Literal("auto"),
+            ],
+            {
+              description: "Background style (default: auto)",
+            }
+          )
+        ),
+        format: Type.Optional(
+          Type.Union(
+            [Type.Literal("png"), Type.Literal("jpeg"), Type.Literal("webp")],
+            {
+              description: "Output image format (default: png)",
+            }
+          )
+        ),
+      }),
+      run: (args) => generateImage(gw, args),
+    }),
+
+    defineTool({
+      name: "GenerateAudio",
+      description: getCustomToolDescription("GenerateAudio"),
+      parameters: Type.Object({
+        text: Type.String({
+          description: "The text to convert to speech (max 4096 characters)",
+        }),
+        voice: Type.Optional(
+          Type.String({
+            description:
+              "Voice ID (provider-specific). OpenAI: alloy, echo, fable, onyx, nova, shimmer. Leave empty for default.",
+          })
+        ),
+        speed: Type.Optional(
+          Type.Number({
+            description: "Speech speed (0.5-2.0, default 1.0).",
+          })
+        ),
+      }),
+      run: (args) => generateAudio(gw, args),
+    }),
+
+    defineTool({
+      name: "GetChannelHistory",
+      description: getCustomToolDescription("GetChannelHistory"),
+      parameters: Type.Object({
+        limit: Type.Optional(
+          Type.Number({
+            description: "Number of messages to fetch (default 50, max 100)",
+          })
+        ),
+        before: Type.Optional(
+          Type.String({
+            description:
+              "ISO timestamp cursor - fetch messages before this time (for pagination)",
+          })
+        ),
+      }),
+      run: (args) => getChannelHistory(gw, args),
+    }),
+
+    defineTool({
+      name: "AskUserQuestion",
+      description: getCustomToolDescription("AskUserQuestion"),
+      parameters: Type.Object({
+        question: Type.String({
+          description: "The question to ask the user",
+        }),
+        options: Type.Array(Type.String(), {
+          description: "Array of button labels for the user to choose from",
+        }),
+      }),
+      run: (args) => askUserQuestion(gw, args),
+    }),
+  ];
+
+  return tools;
+}
+
+/**
+ * Convert MCP tool definitions from session context into first-class
+ * OpenClaw ToolDefinition objects that call the MCP proxy directly.
+ * Tools are dynamically discovered from each MCP server (e.g. lobu).
+ */
+export function createMcpToolDefinitions(
+  mcpTools: Record<string, McpToolDef[]>,
+  gw: GatewayParams,
+  mcpContext?: Record<string, string>
+): ToolDefinition[] {
+  const tools: ToolDefinition[] = [];
+
+  for (const [mcpId, defs] of Object.entries(mcpTools)) {
+    const contextPrefix = mcpContext?.[mcpId];
+    for (const def of defs) {
+      if (!def.name || typeof def.name !== "string" || !def.name.trim()) {
+        continue;
+      }
+      const schema = def.inputSchema
+        ? Type.Unsafe(def.inputSchema)
+        : Type.Object({});
+
+      const baseDescription = def.description || `MCP tool from ${mcpId}`;
+      const description = contextPrefix
+        ? `[${contextPrefix}] ${baseDescription}`
+        : baseDescription;
+
+      tools.push({
+        name: def.name,
+        label: `${mcpId}/${def.name}`,
+        description,
+        parameters: schema,
+        execute: async (_toolCallId, args) =>
+          toToolResult(
+            await callMcpTool(
+              gw,
+              mcpId,
+              def.name,
+              (args || {}) as Record<string, unknown>
+            )
+          ),
+      });
+    }
+  }
+
+  return tools;
+}
+
+export function createMcpAuthToolDefinitions(
+  mcpStatus: Array<{
+    id: string;
+    name: string;
+    requiresAuth: boolean;
+    requiresInput?: boolean;
+    authenticated?: boolean;
+    configured?: boolean;
+  }>,
+  gw: GatewayParams,
+  existingToolNames: Set<string> = new Set()
+): ToolDefinition[] {
+  const tools: ToolDefinition[] = [];
+
+  for (const mcp of mcpStatus) {
+    if (!mcp.requiresAuth) {
+      continue;
+    }
+
+    const loginToolName = `${mcp.id}_login`;
+    if (!existingToolNames.has(loginToolName)) {
+      tools.push(
+        defineTool({
+          name: loginToolName,
+          description: `Start the authentication flow for the ${mcp.name} MCP. Use this when ${mcp.name} requires login before its tools can be used.`,
+          parameters: Type.Object({}),
+          run: () => startMcpLogin(gw, { mcpId: mcp.id }),
+        })
+      );
+      existingToolNames.add(loginToolName);
+    }
+
+    const checkToolName = `${mcp.id}_login_check`;
+    if (!existingToolNames.has(checkToolName)) {
+      tools.push(
+        defineTool({
+          name: checkToolName,
+          description: `Check whether authentication for the ${mcp.name} MCP has completed. Call this after the user finishes login.`,
+          parameters: Type.Object({}),
+          run: () => checkMcpLogin(gw, { mcpId: mcp.id }),
+        })
+      );
+      existingToolNames.add(checkToolName);
+    }
+
+    const logoutToolName = `${mcp.id}_logout`;
+    if (!existingToolNames.has(logoutToolName)) {
+      tools.push(
+        defineTool({
+          name: logoutToolName,
+          description: `Remove the stored authentication credential for the ${mcp.name} MCP.`,
+          parameters: Type.Object({}),
+          run: () => logoutMcp(gw, { mcpId: mcp.id }),
+        })
+      );
+      existingToolNames.add(logoutToolName);
+    }
+  }
+
+  return tools;
+}

package/src/openclaw/instructions.ts

@@ -0,0 +1,36 @@
+import {
+  BaseInstructionProvider,
+  type InstructionContext,
+  renderAlwaysOnToolPolicyRules,
+  renderBaselineAgentPolicy,
+  renderDetectedToolIntentRules,
+} from "@lobu/core";
+
+/**
+ * OpenClaw core instructions
+ */
+export class OpenClawCoreInstructionProvider extends BaseInstructionProvider {
+  readonly name = "core";
+  readonly priority = 10;
+
+  protected buildInstructions(context: InstructionContext): string {
+    return [
+      `You are a Lobu agent for user ${context.userId}.`,
+      `Working directory: ${context.workingDirectory}`,
+      renderBaselineAgentPolicy(),
+      renderAlwaysOnToolPolicyRules(),
+      `## Image Analysis
+
+If the user asks to analyze an uploaded image, use the image content already attached to the prompt and provide direct analysis.`,
+    ].join("\n\n");
+  }
+}
+
+export class OpenClawPromptIntentInstructionProvider extends BaseInstructionProvider {
+  readonly name = "prompt-intent";
+  readonly priority = 15;
+
+  protected buildInstructions(context: InstructionContext): string {
+    return renderDetectedToolIntentRules(context.userPrompt || "");
+  }
+}