@lobu/worker 3.0.5 → 3.0.6

package/USAGE.md

@@ -0,0 +1,120 @@
+# Worker Environment Variables
+
+This document describes all environment variables used by Lobu Workers. Most of these are automatically set by the Gateway orchestrator and should not be manually configured.
+
+## Gateway-Managed Variables (Auto-Set)
+
+These variables are automatically set by the Gateway when deploying worker containers. **Do not manually configure these.**
+
+### `DISPATCHER_URL`
+**Description**: Gateway URL for worker-to-gateway communication
+**Format**: HTTP URL
+**Example**: `http://gateway:8080/worker/stream`
+**Set by**: Gateway orchestrator
+**Used by**: SSE connection to gateway, progress updates, session management
+
+### `WORKER_TOKEN`
+**Description**: Authentication token for worker-gateway communication
+**Format**: JWT token or user-specific token
+**Set by**: Gateway orchestrator
+**Used by**: Worker authentication, gateway proxy authentication
+
+### `DEPLOYMENT_NAME`
+**Description**: Unique identifier for this worker deployment
+**Format**: `lobu-worker-{user}-{timestamp}-{random}`
+**Example**: `lobu-worker-u123abc-284-707819`
+**Set by**: Gateway orchestrator
+**Used by**: Deployment identification, logging
+
+### `USER_ID`
+**Description**: Platform-specific user identifier
+**Format**: Platform-dependent (e.g., Slack user ID starts with `U`)
+**Example**: `U0123456789`
+**Set by**: Gateway orchestrator (updated on first message)
+**Used by**: User-specific credential lookup, session management
+
+### `THREAD_ID`
+**Description**: Platform thread identifier for conversation context
+**Format**: Platform-dependent
+**Example**: `1234567890.123456`
+**Set by**: Gateway orchestrator
+**Used by**: Workspace isolation, session continuity
+
+### `WORKSPACE_DIR`
+**Description**: Worker workspace directory path
+**Format**: Absolute path
+**Default**: `/workspace`
+**Set by**: Worker initialization
+**Used by**: File operations, MCP process working directory
+
+### `HOME`
+**Description**: Home directory for worker processes
+**Format**: Absolute path
+**Default**: `/workspace` (to persist agent sessions)
+**Set by**: Gateway orchestrator
+**Used by**: Agent session storage
+
+### `HOSTNAME`
+**Description**: Container hostname (fallback for DEPLOYMENT_NAME)
+**Format**: Alphanumeric string
+**Set by**: Container runtime
+**Used by**: Deployment identification if DEPLOYMENT_NAME not set
+
+## MCP Configuration
+
+### `MCP_SERVER_CONFIG`
+**Description**: JSON configuration for MCP servers (auto-generated)
+**Format**: JSON string
+**Set by**: Worker initialization (from user credentials)
+**Used by**: MCP server initialization
+
+## Development/Debugging Variables
+
+### `DEBUG`
+**Description**: Enable debug logging
+**Format**: `1` or any truthy value
+**Example**: `DEBUG=1`
+**Set by**: Gateway orchestrator in development mode
+**Used by**: Enhanced logging, crash debugging
+
+### `NODE_ENV`
+**Description**: Environment mode
+**Values**: `development` | `production`
+**Set by**: Gateway orchestrator
+**Used by**: Logging verbosity, error handling
+
+## Container Runtime Variables
+
+These are automatically set by the container runtime:
+
+### Read-Only Root Filesystem
+**Default**: Enabled (`WORKER_READONLY_ROOTFS=true` in gateway)
+**Writable paths**:
+- `/workspace` - Worker workspace (persistent via volume)
+- `/tmp` - Temporary files (100MB tmpfs)
+- `/home/bun/.cache` - Bun cache (200MB tmpfs)
+
+### Security Configuration
+**Capabilities**: All dropped by default (CapDrop: ALL)
+**Privilege Escalation**: Disabled (no-new-privileges)
+**Seccomp**: Docker's default profile
+**AppArmor**: Docker's default profile
+
+## Summary
+
+**For normal operation, workers require NO manual environment configuration.** The Gateway orchestrator automatically sets all necessary variables when deploying worker containers.
+
+### Minimal Auto-Set Variables (by Gateway):
+```bash
+DISPATCHER_URL=http://gateway:8080/worker/stream
+WORKER_TOKEN=<auto-generated>
+DEPLOYMENT_NAME=lobu-worker-<user>-<timestamp>
+HOME=/workspace
+```
+
+### Optional Gateway-Passed Variables:
+```bash
+DEBUG=1  # Development only
+```
+
+All other configuration is handled automatically by the worker based on gateway-provided context.

package/docs/custom-base-image.md

@@ -0,0 +1,88 @@
+# Using @lobu/worker with Custom Base Images
+
+Install and run the Lobu worker in your own Docker base image instead of extending the default `ghcr.io/lobu-ai/lobu-worker-base`.
+
+## System Requirements
+
+| Dependency | Version | Required |
+|------------|---------|----------|
+| Node.js or Bun | >= 18.0 | Yes — worker runtime |
+| Git | >= 2.30 | Yes — code operations |
+| Docker CLI | >= 20.10 | Optional — spawning sub-containers |
+| Python | >= 3.9 | Optional — Python tools |
+
+## Installation
+
+### Bun (Recommended)
+
+```dockerfile
+FROM oven/bun:1.2.9-alpine
+
+RUN apk add --no-cache docker-cli git python3 py3-pip
+
+RUN bun add -g @lobu/worker@^0.1.0
+
+CMD ["lobu-worker"]
+```
+
+### Node.js
+
+```dockerfile
+FROM node:20-alpine
+
+RUN apk add --no-cache docker-cli git python3 py3-pip curl
+
+RUN npm install -g @lobu/worker@^0.1.0
+
+CMD ["lobu-worker"]
+```
+
+### Company Approved Base
+
+```dockerfile
+FROM company-registry.example.com/ubuntu:22.04
+
+RUN apt-get update && apt-get install -y \
+    nodejs npm docker.io git python3 curl
+
+RUN npm install -g @lobu/worker@^0.1.0
+
+CMD ["lobu-worker"]
+```
+
+## Environment Variables
+
+All variables are auto-set by the gateway orchestrator. Manual configuration is not required.
+
+```bash
+# Auto-set by gateway (do not configure manually)
+DISPATCHER_URL=http://gateway:8080/worker/stream
+WORKER_TOKEN=<auto-generated>
+DEPLOYMENT_NAME=lobu-worker-<user>-<timestamp>
+USER_ID=<platform-user-id>
+HOME=/workspace
+```
+
+See [USAGE.md](../USAGE.md) for the full variable reference.
+
+## Compatibility Matrix
+
+| Base Image | Status | Notes |
+|------------|--------|-------|
+| `oven/bun:1.2.9` | Tested | Best performance |
+| `node:20-alpine` | Tested | Small size |
+| `node:20-slim` | Tested | Debian-based |
+| `ubuntu:22.04` | Tested | Most compatible |
+| `alpine:3.19` | Tested | Must install Node separately |
+
+## Troubleshooting
+
+**`lobu-worker: command not found`** — Ensure the package was installed globally (`npm install -g` or `bun add -g`).
+
+**`git: command not found`** — Install git in your base image (`apk add git` or `apt-get install git`).
+
+**`EACCES: permission denied`** — Run as root or add user to the docker group.
+
+## Getting Help
+
+- [GitHub Issues](https://github.com/lobu-ai/lobu/issues)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lobu/worker",
-  "version": "3.0.5",
+  "version": "3.0.6",
   "description": "Lobu worker runtime - run in your own Docker image or use our base image",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@hono/node-server": "^1.19.9",
-    "@lobu/core": "3.0.5",
+    "@lobu/core": "workspace:*",
     "@lobu/owletto-openclaw": "^3.0.2",
     "@mariozechner/pi-agent-core": "^0.51.6",
     "@mariozechner/pi-ai": "^0.51.6",

package/scripts/worker-entrypoint.sh

@@ -0,0 +1,184 @@
+#!/bin/bash
+set -e
+
+# Container entrypoint script for Lobu Worker
+echo "🚀 Starting Lobu Worker..."
+
+# Function to handle cleanup on exit
+cleanup() {
+    echo "📦 Container shutting down, performing cleanup..."
+    
+    # Kill any background processes
+    jobs -p | xargs -r kill || true
+    
+    # Give processes time to exit gracefully
+    sleep 2
+    
+    echo "✅ Cleanup completed"
+    exit 0
+}
+
+# Setup signal handlers for graceful shutdown
+trap cleanup SIGTERM SIGINT
+
+echo "🔍 Environment variables provided by orchestrator:"
+echo "  - USER_ID: ${USER_ID:-not set}" 
+echo "  - CHANNEL_ID: ${CHANNEL_ID:-not set}"
+echo "  - REPOSITORY_URL: ${REPOSITORY_URL:-not set}"
+echo "  - DEPLOYMENT_NAME: ${DEPLOYMENT_NAME:-not set}"
+
+# Basic validation for critical variables
+if [[ -z "${USER_ID:-}" ]]; then
+    echo "❌ Error: USER_ID is required"
+    exit 1
+fi
+
+if [[ -z "${DEPLOYMENT_NAME:-}" ]]; then
+    echo "❌ Error: DEPLOYMENT_NAME is required"
+    exit 1
+fi
+
+# Setup workspace directory
+echo "📁 Setting up workspace directory..."
+WORKSPACE_DIR="/workspace"
+
+# Workspace permissions are fixed by gateway before container starts
+# Just verify we can write to it
+if [ ! -w "$WORKSPACE_DIR" ]; then
+    echo "❌ Error: Cannot write to workspace directory $WORKSPACE_DIR"
+    exit 1
+fi
+
+# Route temp files and cache to workspace-backed paths.
+# Keep /tmp mounted for compatibility with tools that ignore TMPDIR.
+export TMPDIR="${TMPDIR:-$WORKSPACE_DIR/.tmp}"
+export TMP="${TMP:-$TMPDIR}"
+export TEMP="${TEMP:-$TMPDIR}"
+export XDG_CACHE_HOME="${XDG_CACHE_HOME:-$WORKSPACE_DIR/.cache}"
+mkdir -p "$TMPDIR" "$XDG_CACHE_HOME"
+
+cd "$WORKSPACE_DIR"
+
+echo "✅ Workspace directory ready: $WORKSPACE_DIR"
+
+# Log container information
+echo "📊 Container Information:"
+echo "  - Session Key: $SESSION_KEY"
+echo "  - Repository: $REPOSITORY_URL"
+echo "  - Working Directory: $(pwd)"
+echo "  - Container Hostname: $(hostname)"
+echo "  - Container Memory Limit: $(cat /sys/fs/cgroup/memory.max 2>/dev/null || echo 'unknown')"
+echo "  - Container CPU Limit: $(cat /sys/fs/cgroup/cpu.max 2>/dev/null || echo 'unknown')"
+
+# Setup git global configuration
+echo "⚙️ Setting up git configuration..."
+git config --global user.name "Lobu Worker"
+git config --global user.email "lobu@noreply.github.com"
+git config --global init.defaultBranch main
+git config --global pull.rebase false
+git config --global safe.directory '*'
+
+# In development mode, ensure core package can find its dependencies
+# The packages/ dir is mounted as a volume which may contain node_modules from host
+if [ "${NODE_ENV}" = "development" ]; then
+    # Remove any existing node_modules that aren't symlinks (non-fatal on read-only rootfs)
+    if [ -e "/app/packages/core/node_modules" ] && [ ! -L "/app/packages/core/node_modules" ]; then
+        echo "🗑️  Removing host node_modules from /app/packages/core/"
+        rm -rf /app/packages/core/node_modules 2>/dev/null || true
+    fi
+    if [ ! -e "/app/packages/core/node_modules" ]; then
+        echo "🔗 Creating symlink for core package dependencies..."
+        ln -sf /app/node_modules /app/packages/core/node_modules 2>/dev/null || true
+    fi
+
+    # Also for worker package if needed (non-fatal on read-only rootfs)
+    if [ -e "/app/packages/worker/node_modules" ] && [ ! -L "/app/packages/worker/node_modules" ]; then
+        rm -rf /app/packages/worker/node_modules 2>/dev/null || true
+    fi
+    if [ ! -e "/app/packages/worker/node_modules" ]; then
+        ln -sf /app/node_modules /app/packages/worker/node_modules 2>/dev/null || true
+    fi
+fi
+
+# Source Nix profile if installed (non-interactive shells don't source /etc/profile.d)
+if [ -f /home/worker/.nix-profile/etc/profile.d/nix.sh ]; then
+    . /home/worker/.nix-profile/etc/profile.d/nix.sh
+    # Set NIX_PATH for nix-shell -p to find nixpkgs
+    export NIX_PATH="nixpkgs=/home/worker/.nix-defexpr/channels/nixpkgs"
+fi
+
+# Docker fallback: persist Nix store on workspace PVC via symlinks
+# (K8s uses init container + subPath mounts instead, detected by .nix-pvc-mounted marker)
+if [ -n "${NIX_PACKAGES:-}${NIX_FLAKE_URL:-}" ] && [ ! -d "/nix/store/.nix-pvc-mounted" ]; then
+    NIX_PVC_STORE="/workspace/.nix-store"
+    NIX_PVC_VAR="/workspace/.nix-var"
+    MARKER="/workspace/.nix-bootstrapped"
+    if [ ! -f "$MARKER" ]; then
+        echo "Bootstrapping Nix store to PVC..."
+        cp -a /nix/store "$NIX_PVC_STORE"
+        cp -a /nix/var "$NIX_PVC_VAR"
+        touch "$MARKER"
+    fi
+    rm -rf /nix/store /nix/var
+    ln -sf "$NIX_PVC_STORE" /nix/store
+    ln -sf "$NIX_PVC_VAR" /nix/var
+    echo "Nix store linked to PVC"
+fi
+
+# Nix environment activation
+# Priority: API env vars > repo files
+activate_nix_env() {
+    local cmd="$1"
+
+    # Check if Nix is installed
+    if ! command -v nix &> /dev/null; then
+        echo "⚠️  Nix not installed, skipping environment activation"
+        exec $cmd
+    fi
+
+    # 1. API-provided flake URL takes highest priority
+    if [ -n "${NIX_FLAKE_URL:-}" ]; then
+        echo "🔧 Activating Nix flake environment: $NIX_FLAKE_URL"
+        exec nix develop "$NIX_FLAKE_URL" --command $cmd
+    fi
+
+    # 2. API-provided packages list
+    if [ -n "${NIX_PACKAGES:-}" ]; then
+        # Convert comma-separated to space-separated
+        local packages="${NIX_PACKAGES//,/ }"
+        echo "🔧 Activating Nix packages: $packages"
+        exec nix-shell -p $packages --command "$cmd"
+    fi
+
+    # 3. Check for nix files in workspace (git-based config)
+    if [ -f "$WORKSPACE_DIR/flake.nix" ]; then
+        echo "🔧 Detected flake.nix in workspace, activating..."
+        exec nix develop "$WORKSPACE_DIR" --command $cmd
+    fi
+
+    if [ -f "$WORKSPACE_DIR/shell.nix" ]; then
+        echo "🔧 Detected shell.nix in workspace, activating..."
+        exec nix-shell "$WORKSPACE_DIR/shell.nix" --command "$cmd"
+    fi
+
+    # 4. Check for simple .nix-packages file (one package per line)
+    if [ -f "$WORKSPACE_DIR/.nix-packages" ]; then
+        local packages=$(cat "$WORKSPACE_DIR/.nix-packages" | tr '\n' ' ')
+        echo "🔧 Detected .nix-packages file, activating: $packages"
+        exec nix-shell -p $packages --command "$cmd"
+    fi
+
+    # No nix config found, run directly
+    exec $cmd
+}
+
+# Start the worker process
+echo "🚀 Executing Worker..."
+# Check if we're already in the worker directory
+if [ "$(pwd)" != "/app/packages/worker" ]; then
+    cd /app/packages/worker || { echo "❌ Failed to cd to /app/packages/worker"; exit 1; }
+fi
+
+# Always run from source — Bun handles TypeScript natively and this avoids
+# CJS/ESM interop issues with ESM-only dependencies (e.g. pi-coding-agent).
+activate_nix_env "bun run src/index.ts"

package/src/__tests__/audio-provider-suggestions.test.ts

@@ -0,0 +1,198 @@
+import { afterEach, describe, expect, mock, test } from "bun:test";
+import { OpenClawWorker } from "../openclaw/worker";
+import {
+  fetchAudioProviderSuggestions,
+  normalizeAudioProviderSuggestions,
+} from "../shared/audio-provider-suggestions";
+import { generateAudio } from "../shared/tool-implementations";
+
+const originalFetch = globalThis.fetch;
+
+function extractText(result: {
+  content: Array<{ type: "text"; text: string }>;
+}): string {
+  return result.content[0]?.text || "";
+}
+
+describe("audio provider suggestions", () => {
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    mock.restore();
+  });
+
+  test("normalizes gateway capability providers into prefill IDs + display list", () => {
+    const normalized = normalizeAudioProviderSuggestions({
+      available: false,
+      providers: [
+        { provider: "openai", name: "OpenAI" },
+        { provider: "gemini", name: "Google Gemini" },
+      ],
+    });
+
+    expect(normalized.available).toBe(false);
+    expect(normalized.usedFallback).toBe(false);
+    expect(normalized.providerIds).toEqual(["chatgpt", "openai", "gemini"]);
+    expect(normalized.providerDisplayList).toBe("OpenAI, Google Gemini");
+  });
+
+  test("falls back safely when capability payload is malformed", () => {
+    const normalized = normalizeAudioProviderSuggestions({
+      available: true,
+      providers: [{ unexpected: "value" }],
+    });
+
+    expect(normalized.available).toBe(true);
+    expect(normalized.usedFallback).toBe(true);
+    expect(normalized.providerIds).toEqual(["chatgpt", "gemini", "elevenlabs"]);
+    expect(normalized.providerDisplayList).toBe("");
+  });
+
+  test("falls back safely when capability fetch fails", async () => {
+    globalThis.fetch = mock(async () => {
+      throw new Error("network down");
+    }) as unknown as typeof fetch;
+
+    const normalized = await fetchAudioProviderSuggestions({
+      gatewayUrl: "http://gateway",
+      workerToken: "token",
+    });
+
+    expect(normalized.available).toBeNull();
+    expect(normalized.usedFallback).toBe(true);
+    expect(normalized.providerIds).toEqual(["chatgpt", "gemini", "elevenlabs"]);
+    expect(normalized.providerDisplayList).toBe("");
+  });
+});
+
+describe("GenerateAudio dynamic provider messaging", () => {
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    mock.restore();
+  });
+
+  test("uses dynamic capability providers in missing-scope guidance", async () => {
+    const fetchMock = mock(
+      async (input: RequestInfo | URL, init?: RequestInit) => {
+        const url = String(input);
+
+        if (url.endsWith("/internal/audio/capabilities")) {
+          return new Response(
+            JSON.stringify({
+              available: true,
+              providers: [
+                { provider: "openai", name: "OpenAI" },
+                { provider: "gemini", name: "Google Gemini" },
+              ],
+            }),
+            { status: 200, headers: { "Content-Type": "application/json" } }
+          );
+        }
+
+        if (url.endsWith("/internal/audio/synthesize")) {
+          expect(init?.method).toBe("POST");
+          return new Response(
+            JSON.stringify({
+              error: "missing_scope: api.model.audio.request",
+            }),
+            { status: 400, headers: { "Content-Type": "application/json" } }
+          );
+        }
+
+        throw new Error(`Unexpected URL: ${url}`);
+      }
+    );
+
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+    const result = await generateAudio(
+      {
+        gatewayUrl: "http://gateway",
+        workerToken: "token",
+        channelId: "ch",
+        conversationId: "conv",
+        platform: "telegram",
+      },
+      { text: "hello world" }
+    );
+
+    const text = extractText(result as any);
+
+    expect(text).toContain("OpenAI, Google Gemini");
+    expect(text).toContain("Ask an admin");
+  });
+});
+
+describe("OpenClawWorker audio permission hint", () => {
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    mock.restore();
+  });
+
+  test("uses dynamic providers in admin guidance", async () => {
+    const fetchMock = mock(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.endsWith("/internal/audio/capabilities")) {
+        return new Response(
+          JSON.stringify({
+            available: true,
+            providers: [
+              { provider: "openai", name: "OpenAI" },
+              { provider: "elevenlabs", name: "ElevenLabs" },
+            ],
+          }),
+          { status: 200, headers: { "Content-Type": "application/json" } }
+        );
+      }
+      throw new Error(`Unexpected URL: ${url}`);
+    });
+
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+    const hint = await (
+      OpenClawWorker.prototype as any
+    ).maybeBuildAudioPermissionHintMessage(
+      "Audio generation failed because token lacks api.model.audio.request",
+      "http://gateway",
+      "token"
+    );
+
+    expect(hint).toContain("OpenAI, ElevenLabs");
+    expect(hint).toContain("Ask an admin");
+  });
+
+  test("falls back to generic provider suggestions when capabilities lookup fails", async () => {
+    const fetchMock = mock(async () => {
+      throw new Error("capabilities unavailable");
+    });
+
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+    const hint = await (
+      OpenClawWorker.prototype as any
+    ).maybeBuildAudioPermissionHintMessage(
+      "api.model.audio.request is missing",
+      "http://gateway",
+      "token"
+    );
+
+    expect(hint).toBeNull();
+  });
+});
+
+describe("OpenClawWorker auth hint messaging", () => {
+  test("routes missing provider auth to admin guidance", async () => {
+    const hint = await (
+      OpenClawWorker.prototype as any
+    ).maybeBuildAuthHintMessage(
+      'Authentication failed for "openai"',
+      "openai",
+      "gpt-4.1",
+      "http://gateway",
+      "token"
+    );
+
+    expect(hint).toContain("gpt-4.1");
+    expect(hint).toContain("admin");
+    expect(hint).toContain("openai");
+  });
+});

package/src/__tests__/embedded-just-bash-bootstrap.test.ts

@@ -0,0 +1,39 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { buildBinaryInvocation } from "../embedded/just-bash-bootstrap";
+
+const tempDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe("buildBinaryInvocation", () => {
+  test("runs node shebang scripts through node", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "lobu-owletto-"));
+    tempDirs.push(dir);
+    const scriptPath = path.join(dir, "owletto");
+    fs.writeFileSync(
+      scriptPath,
+      "#!/usr/bin/env node\nconsole.log('ok');\n",
+      "utf8"
+    );
+    fs.chmodSync(scriptPath, 0o755);
+
+    expect(buildBinaryInvocation(scriptPath, ["version"])).toEqual({
+      command: "node",
+      args: [scriptPath, "version"],
+    });
+  });
+
+  test("executes normal binaries directly", () => {
+    expect(buildBinaryInvocation("/bin/echo", ["hello"])).toEqual({
+      command: "/bin/echo",
+      args: ["hello"],
+    });
+  });
+});