@lobu/worker 7.0.0 → 7.2.0

package/src/__tests__/transcript-snapshot.test.ts

@@ -0,0 +1,275 @@
+/**
+ * Unit tests for the worker-side per-run snapshot helpers
+ * (`hydrateFromSnapshot`, `writeSnapshot`).
+ *
+ * These exercise the HTTP-client side of the snapshot path against a mocked
+ * gateway. Coverage:
+ *  - Hydrate writes the gateway's bytes verbatim to disk, fsyncs, returns
+ *    the post-hydrate file size matching the byte_size column contract.
+ *  - Hydrate handles 404 (no completed snapshot) → returns false, leaves
+ *    the local file untouched.
+ *  - Hydrate failures are non-fatal at the caller's discretion (we re-throw,
+ *    caller logs+continues; behaviour verified in worker.ts but we assert
+ *    the throw shape here).
+ *  - writeSnapshot reads the session file, POSTs body, handles 409 (race
+ *    win), missing file (early-exit worker), and empty file all silently.
+ *  - The transport layer never throws — `cleanup()` runs in the worker's
+ *    dying breath and any throw would abort the surrounding `finally`.
+ *
+ * The gateway test (`packages/server/src/gateway/__tests__/
+ * agent-transcript-snapshot.test.ts`) covers the route + PG side; this
+ * file is the symmetric client side.
+ */
+
+import { promises as fs } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import {
+  hydrateFromSnapshot,
+  writeSnapshot,
+} from "../openclaw/transcript-snapshot";
+
+let tmp: string;
+let originalFetch: typeof globalThis.fetch;
+
+beforeEach(async () => {
+  tmp = await mkdtemp(join(tmpdir(), "snapshot-test-"));
+  originalFetch = globalThis.fetch;
+});
+
+afterEach(async () => {
+  globalThis.fetch = originalFetch;
+  await rm(tmp, { recursive: true, force: true });
+});
+
+function stubFetch(
+  handler: (url: string, init: RequestInit) => Response
+): void {
+  globalThis.fetch = mock(
+    async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = typeof input === "string" ? input : input.toString();
+      return handler(url, init ?? {});
+    }
+  ) as unknown as typeof globalThis.fetch;
+}
+
+describe("hydrateFromSnapshot", () => {
+  test("boot-hydrate-fsync: writes bytes verbatim, file size matches body length", async () => {
+    const sessionFile = join(tmp, ".openclaw", "session.jsonl");
+    const expected =
+      `{"type":"session","version":3,"id":"hydrate","timestamp":"2026-05-18T10:00:00Z","cwd":"/w"}\n` +
+      `{"type":"message","id":"m1","parentId":null,"timestamp":"2026-05-18T10:00:01Z","message":{"role":"user","content":[{"type":"text","text":"resume"}]}}\n`;
+
+    stubFetch((url, init) => {
+      expect(url.endsWith("/worker/transcript/snapshot")).toBe(true);
+      expect(init.method).toBe("GET");
+      expect((init.headers as Record<string, string>).Authorization).toBe(
+        "Bearer test-jwt"
+      );
+      return new Response(expected, { status: 200 });
+    });
+
+    const hydrated = await hydrateFromSnapshot({
+      sessionFile,
+      gatewayUrl: "http://gw.test/lobu",
+      workerToken: "test-jwt",
+    });
+    expect(hydrated).toBe(true);
+
+    // File written + fsynced → stat size matches byte_size we'd compute.
+    const stats = await fs.stat(sessionFile);
+    expect(stats.size).toBe(Buffer.byteLength(expected, "utf-8"));
+    const back = await fs.readFile(sessionFile, "utf-8");
+    expect(back).toBe(expected);
+  });
+
+  test("returns false on 404 and does not touch the file", async () => {
+    const sessionFile = join(tmp, ".openclaw", "session.jsonl");
+    stubFetch(() => new Response("", { status: 404 }));
+
+    const hydrated = await hydrateFromSnapshot({
+      sessionFile,
+      gatewayUrl: "http://gw.test/lobu",
+      workerToken: "test-jwt",
+    });
+    expect(hydrated).toBe(false);
+    // No file created.
+    let exists = false;
+    try {
+      await fs.stat(sessionFile);
+      exists = true;
+    } catch {
+      exists = false;
+    }
+    expect(exists).toBe(false);
+  });
+
+  test("throws on non-2xx, non-404 — caller logs + continues with local file", async () => {
+    const sessionFile = join(tmp, ".openclaw", "session.jsonl");
+    stubFetch(() => new Response("boom", { status: 500 }));
+    await expect(
+      hydrateFromSnapshot({
+        sessionFile,
+        gatewayUrl: "http://gw.test/lobu",
+        workerToken: "test-jwt",
+      })
+    ).rejects.toThrow(/transcript hydrate failed: 500/);
+  });
+});
+
+describe("writeSnapshot", () => {
+  test("happy path: reads file, POSTs body + terminalStatus, gateway 200", async () => {
+    const sessionFile = join(tmp, ".openclaw", "session.jsonl");
+    await fs.mkdir(join(tmp, ".openclaw"), { recursive: true });
+    const body =
+      `{"type":"session","version":3,"id":"write","timestamp":"2026-05-18T10:00:00Z","cwd":"/w"}\n` +
+      `{"type":"message","id":"u1","parentId":null,"timestamp":"2026-05-18T10:00:01Z","message":{"role":"user","content":[{"type":"text","text":"hi"}]}}\n`;
+    await fs.writeFile(sessionFile, body, "utf-8");
+
+    let postedBody: string | null = null;
+    stubFetch((url, init) => {
+      expect(url.endsWith("/worker/transcript/snapshot")).toBe(true);
+      expect(init.method).toBe("POST");
+      postedBody = init.body as string;
+      return new Response('{"id":1}', { status: 200 });
+    });
+
+    await writeSnapshot({
+      sessionFile,
+      gatewayUrl: "http://gw.test/lobu",
+      workerToken: "test-jwt",
+      terminalStatus: "completed",
+      runId: 42,
+    });
+    expect(postedBody).not.toBeNull();
+    const parsed = JSON.parse(postedBody!);
+    expect(parsed.snapshotJsonl).toBe(body);
+    expect(parsed.terminalStatus).toBe("completed");
+    // P1#1: runId MUST be on the POST body so the route attributes the
+    // snapshot to the exact run this worker claimed, not "latest run for
+    // (org, agent, conv)".
+    expect(parsed.runId).toBe(42);
+  });
+
+  test("non-completed terminalStatus is skipped (no POST, no waste)", async () => {
+    // Hydrate filters terminal_status='completed' — writing failed/
+    // timeout/cancelled rows is pure network waste. Codex round 2
+    // quality win C on PR #865. The cleanup() path is also gated on
+    // `terminalStatus === "completed"`, but writeSnapshot defends in
+    // depth so any future caller can't accidentally write a row that
+    // hydrate will never read.
+    const sessionFile = join(tmp, ".openclaw", "session.jsonl");
+    await fs.mkdir(join(tmp, ".openclaw"), { recursive: true });
+    await fs.writeFile(sessionFile, `{"type":"session"}\n`, "utf-8");
+
+    let calls = 0;
+    stubFetch(() => {
+      calls++;
+      return new Response("{}", { status: 200 });
+    });
+
+    for (const terminalStatus of ["failed", "timeout", "cancelled"] as const) {
+      await writeSnapshot({
+        sessionFile,
+        gatewayUrl: "http://gw.test/lobu",
+        workerToken: "test-jwt",
+        terminalStatus,
+        runId: 42,
+      });
+    }
+    expect(calls).toBe(0);
+  });
+
+  test("race-win-409 is benign — no throw", async () => {
+    const sessionFile = join(tmp, ".openclaw", "session.jsonl");
+    await fs.mkdir(join(tmp, ".openclaw"), { recursive: true });
+    await fs.writeFile(sessionFile, `{"type":"session"}\n`, "utf-8");
+
+    stubFetch(() => new Response("conflict", { status: 409 }));
+
+    // No throw — cleanup() in the worker's dying breath must never
+    // re-throw inside a `finally`.
+    await writeSnapshot({
+      sessionFile,
+      gatewayUrl: "http://gw.test/lobu",
+      workerToken: "test-jwt",
+      terminalStatus: "completed",
+      runId: 42,
+    });
+  });
+
+  test("no session file (early-exit worker): silently skips, no fetch", async () => {
+    const sessionFile = join(tmp, ".openclaw", "session.jsonl");
+    let calls = 0;
+    stubFetch(() => {
+      calls++;
+      return new Response("", { status: 200 });
+    });
+
+    await writeSnapshot({
+      sessionFile,
+      gatewayUrl: "http://gw.test/lobu",
+      workerToken: "test-jwt",
+      terminalStatus: "failed",
+      runId: 42,
+    });
+    expect(calls).toBe(0);
+  });
+
+  test("empty session file is skipped — never POST an empty snapshot", async () => {
+    const sessionFile = join(tmp, ".openclaw", "session.jsonl");
+    await fs.mkdir(join(tmp, ".openclaw"), { recursive: true });
+    await fs.writeFile(sessionFile, "", "utf-8");
+    let calls = 0;
+    stubFetch(() => {
+      calls++;
+      return new Response("{}", { status: 200 });
+    });
+
+    await writeSnapshot({
+      sessionFile,
+      gatewayUrl: "http://gw.test/lobu",
+      workerToken: "test-jwt",
+      terminalStatus: "completed",
+      runId: 42,
+    });
+    expect(calls).toBe(0);
+  });
+
+  test("server 500 is logged, not thrown", async () => {
+    const sessionFile = join(tmp, ".openclaw", "session.jsonl");
+    await fs.mkdir(join(tmp, ".openclaw"), { recursive: true });
+    await fs.writeFile(sessionFile, `{"type":"session"}\n`, "utf-8");
+    stubFetch(() => new Response("boom", { status: 500 }));
+
+    // No throw — same invariant as the 409 case. Logs go to pino; we
+    // don't assert log content here.
+    await writeSnapshot({
+      sessionFile,
+      gatewayUrl: "http://gw.test/lobu",
+      workerToken: "test-jwt",
+      terminalStatus: "completed",
+      runId: 42,
+    });
+  });
+
+  test("fetch throw is caught — cleanup() must never re-throw", async () => {
+    const sessionFile = join(tmp, ".openclaw", "session.jsonl");
+    await fs.mkdir(join(tmp, ".openclaw"), { recursive: true });
+    await fs.writeFile(sessionFile, `{"type":"session"}\n`, "utf-8");
+    globalThis.fetch = (() => {
+      throw new Error("ECONNREFUSED");
+    }) as unknown as typeof globalThis.fetch;
+
+    // No throw escapes — caller is the cleanup() finally block.
+    await writeSnapshot({
+      sessionFile,
+      gatewayUrl: "http://gw.test/lobu",
+      workerToken: "test-jwt",
+      terminalStatus: "completed",
+      runId: 42,
+    });
+  });
+});

package/src/core/error-handler.ts

@@ -2,10 +2,6 @@ import { createLogger, type WorkerTransport } from "@lobu/core";
 
 const logger = createLogger("worker");
 
-/**
- * Format error message for display
- * Generic error formatter that works for any AI agent
- */
 function formatErrorMessage(error: unknown): string {
   if (!(error instanceof Error)) {
     return `💥 Worker crashed: Unknown error`;
@@ -27,10 +23,6 @@ function classifyError(error: unknown): string | undefined {
   return undefined;
 }
 
-/**
- * Handle execution error - decides between authentication and generic errors
- * Generic error handler that works for any AI agent
- */
 export async function handleExecutionError(
   error: unknown,
   transport: WorkerTransport
@@ -38,25 +30,18 @@ export async function handleExecutionError(
   logger.error("Worker execution failed:", error);
 
   const code = classifyError(error);
+  const errorInstance =
+    error instanceof Error ? error : new Error(String(error));
 
   try {
     if (code) {
-      // Known error — clean message, no "Worker crashed" text
-      await transport.signalError(
-        error instanceof Error ? error : new Error(String(error)),
-        code
-      );
+      await transport.signalError(errorInstance, code);
     } else {
-      // Unknown error — existing behavior
-      const errorMsg = formatErrorMessage(error);
-      await transport.sendStreamDelta(errorMsg, true, true);
-      await transport.signalError(
-        error instanceof Error ? error : new Error(String(error))
-      );
+      await transport.sendStreamDelta(formatErrorMessage(error), true, true);
+      await transport.signalError(errorInstance);
     }
   } catch (gatewayError) {
     logger.error("Failed to send error via gateway:", gatewayError);
-    // Re-throw the original error
     throw error;
   }
 }

package/src/core/types.ts

@@ -1,41 +1,16 @@
 #!/usr/bin/env bun
 
-/**
- * Consolidated types for worker package
- * Merged from: base/types.ts, types.ts, interfaces.ts
- */
-
 import type { WorkerTransport } from "@lobu/core";
 
-// ============================================================================
-// WORKER INTERFACES
-// ============================================================================
-
 /**
- * Interface for worker executors
- * Allows different agent implementations
+ * Interface for worker executors. Allows different agent implementations.
  */
 export interface WorkerExecutor {
-  /**
-   * Execute the worker job
-   */
   execute(): Promise<void>;
-
-  /**
-   * Cleanup worker resources
-   */
   cleanup(): Promise<void>;
-
-  /**
-   * Get the worker transport for sending updates to gateway
-   */
   getWorkerTransport(): WorkerTransport | null;
 }
 
-// ============================================================================
-// WORKER CONFIG & WORKSPACE
-// ============================================================================
-
 export interface WorkerConfig {
   sessionKey: string;
   userId: string;
@@ -53,6 +28,24 @@ export interface WorkerConfig {
   workspace: {
     baseDirectory: string;
   };
+  /**
+   * The runs.id of the row that dispatched this job. Set by the gateway
+   * (MessageConsumer stamps it from the runs-queue claim's job.id) so the
+   * worker's cleanup() snapshot can attribute itself to the correct run
+   * even when a follow-up run for the same conversation has already been
+   * enqueued (codex P1#1 on PR #865). Optional for backward-compatibility
+   * with legacy direct-enqueue paths that don't go through the runs queue.
+   */
+  runId?: number;
+  /**
+   * Per-run worker JWT bound to `runId`. Set by MessageConsumer at
+   * dispatch time and used by cleanup()'s writeSnapshot call as the
+   * Authorization bearer — replaces the deployment-lifetime WORKER_TOKEN
+   * for the snapshot path so the gateway's route can require token-runId
+   * equality with body.runId (codex round 2 finding A on PR #865).
+   * When absent (legacy direct-enqueue), the snapshot write is skipped.
+   */
+  runJobToken?: string;
 }
 
 export interface WorkspaceSetupConfig {
@@ -64,10 +57,6 @@ export interface WorkspaceInfo {
   userDirectory: string;
 }
 
-// ============================================================================
-// PROGRESS & EXECUTION TYPES
-// ============================================================================
-
 /**
  * Progress update from AI agent execution
  */
@@ -109,11 +98,6 @@ export type ProgressUpdate =
       timestamp: number;
     };
 
-/**
- * Session context for AI execution
- * Contains information about the current session (platform, user, workspace)
- */
-
 /**
  * Result from session execution (includes session metadata)
  */

package/src/core/workspace.ts

@@ -8,17 +8,12 @@ import type { WorkspaceInfo, WorkspaceSetupConfig } from "./types";
 
 const logger = createLogger("workspace");
 
-// ============================================================================
-// WORKSPACE MANAGER
-// ============================================================================
-
 /**
- * Simplified WorkspaceManager - only handles directory creation.
- * All VCS operations (git, etc.) are handled by modules via hooks.
- *
  * Workspace layout:
  *   baseDirectory/                      ← agent-level root (e.g. /workspace)
  *   baseDirectory/{conversationId}/     ← thread-specific working directory
+ *
+ * VCS operations (git, etc.) are handled by modules via hooks.
  */
 export class WorkspaceManager {
   private config: WorkspaceSetupConfig;
@@ -28,39 +23,23 @@ export class WorkspaceManager {
     this.config = config;
   }
 
-  /**
-   * Setup workspace directory - creates thread-specific directory only.
-   * VCS operations are handled by module hooks (e.g., GitHub module).
-   */
   async setupWorkspace(
     username: string,
     sessionKey?: string
   ): Promise<WorkspaceInfo> {
-    try {
-      const conversationId =
-        process.env.CONVERSATION_ID || sessionKey || username || "default";
+    const conversationId =
+      process.env.CONVERSATION_ID || sessionKey || username || "default";
 
-      logger.info(
-        `Setting up workspace directory for ${username}, conversation: ${conversationId}...`
-      );
-
-      const sanitized = sanitizeConversationId(conversationId);
-      const userDirectory = `${this.config.baseDirectory}/${sanitized}`;
+    logger.info(
+      `Setting up workspace directory for ${username}, conversation: ${conversationId}...`
+    );
 
-      // Ensure directories exist
-      await this.ensureDirectory(this.config.baseDirectory);
-      await this.ensureDirectory(userDirectory);
+    const sanitized = sanitizeConversationId(conversationId);
+    const userDirectory = `${this.config.baseDirectory}/${sanitized}`;
 
-      this.workspaceInfo = {
-        baseDirectory: this.config.baseDirectory,
-        userDirectory,
-      };
-
-      logger.info(
-        `Workspace directory setup completed for ${username} (conversation: ${conversationId}) at ${userDirectory}`
-      );
-
-      return this.workspaceInfo;
+    try {
+      await mkdir(this.config.baseDirectory, { recursive: true });
+      await mkdir(userDirectory, { recursive: true });
     } catch (error) {
       throw new WorkspaceError(
         "setupWorkspace",
@@ -68,21 +47,19 @@ export class WorkspaceManager {
         error as Error
       );
     }
-  }
 
-  private async ensureDirectory(path: string): Promise<void> {
-    try {
-      await mkdir(path, { recursive: true });
-    } catch (error: any) {
-      if (error.code !== "EEXIST") {
-        throw error;
-      }
-    }
+    this.workspaceInfo = {
+      baseDirectory: this.config.baseDirectory,
+      userDirectory,
+    };
+
+    logger.info(
+      `Workspace directory setup completed for ${username} (conversation: ${conversationId}) at ${userDirectory}`
+    );
+
+    return this.workspaceInfo;
   }
 
-  /**
-   * Get current working directory (thread-specific).
-   */
   getCurrentWorkingDirectory(): string {
     return this.workspaceInfo?.userDirectory || this.config.baseDirectory;
   }

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

@@ -248,6 +248,13 @@ async function buildCustomCommands(
         } else if (ctx.env && typeof ctx.env === "object") {
           Object.assign(envRecord, ctx.env);
         }
+        // The agent can `export WORKER_TOKEN=...` inside just-bash to slip a
+        // value through `ctx.env`. Re-strip so spawned binaries (and anything
+        // that may echo or log env) never see a sensitive-shaped key, even an
+        // attacker-controlled one.
+        for (const key of SENSITIVE_WORKER_ENV_KEYS) {
+          delete envRecord[key];
+        }
 
         // Pin HOME / TMPDIR to dedicated subdirs so tool dotfiles (~/.gitconfig,
         // ~/.cache, ~/.config) and temp files don't collide with workspace
@@ -413,14 +420,39 @@ export async function createEmbeddedBashOps(
   }
   const bashFs = new ReadWriteFs({ root: workspaceDir });
 
-  // Parse allowed domains from env var (set by gateway)
+  // Parse allowed domains from env var (set by gateway).
+  // Defense-in-depth: the gateway is trusted, but a malformed env (non-array,
+  // non-string entries, embedded "/" or whitespace) would either crash
+  // `.flatMap(...)` or, worse, expand an "allow https://${domain}/" prefix
+  // into something attacker-shaped (`evil.com/ ` or `attacker.com/path`).
+  // Validate the parsed shape and the per-domain syntax explicitly.
+  const DOMAIN_PATTERN = /^[A-Za-z0-9.*_-]+(?::\d+)?$/;
   let allowedDomains: string[] = [];
   if (process.env.JUST_BASH_ALLOWED_DOMAINS) {
     try {
-      allowedDomains = JSON.parse(process.env.JUST_BASH_ALLOWED_DOMAINS);
-    } catch {
+      const parsed: unknown = JSON.parse(process.env.JUST_BASH_ALLOWED_DOMAINS);
+      if (!Array.isArray(parsed)) {
+        throw new Error("expected a JSON array of domain strings");
+      }
+      const accepted: string[] = [];
+      for (const entry of parsed) {
+        if (typeof entry !== "string") continue;
+        const trimmed = entry.trim();
+        if (!trimmed) continue;
+        if (!DOMAIN_PATTERN.test(trimmed)) {
+          console.warn(
+            `[embedded] Ignoring invalid JUST_BASH_ALLOWED_DOMAINS entry: ${JSON.stringify(entry)}`
+          );
+          continue;
+        }
+        accepted.push(trimmed);
+      }
+      allowedDomains = accepted;
+    } catch (err) {
       console.error(
-        `[embedded] Failed to parse JUST_BASH_ALLOWED_DOMAINS: ${process.env.JUST_BASH_ALLOWED_DOMAINS}`
+        `[embedded] Failed to parse JUST_BASH_ALLOWED_DOMAINS: ${
+          err instanceof Error ? err.message : String(err)
+        }`
       );
     }
   }

package/src/embedded/mcp-cli-commands.ts

@@ -16,7 +16,12 @@
 import type { McpStatus, McpToolDef } from "@lobu/core";
 import { createLogger } from "@lobu/core";
 import type { GatewayParams } from "../shared/tool-implementations";
-import { callMcpTool } from "../shared/tool-implementations";
+import {
+  callMcpTool,
+  checkMcpLogin,
+  logoutMcp,
+  startMcpLogin,
+} from "../shared/tool-implementations";
 import { isDirectPackageInstallCommand } from "../openclaw/tool-policy";
 
 const logger = createLogger("mcp-cli");
@@ -269,11 +274,9 @@ async function runAuthSubcommand(
   ref: McpRuntimeRef
 ): Promise<{ stdout: string; stderr: string; exitCode: number }> {
   const verb = args[0];
-  // Lazy import to avoid a heavy dependency cycle in tests.
-  const impl = await import("../shared/tool-implementations");
 
   if (verb === "login") {
-    const res = await impl.startMcpLogin(gw, { mcpId });
+    const res = await startMcpLogin(gw, { mcpId });
     const text = extractText(res.content);
     return {
       stdout: `${summariseAuthStart(text, mcpId)}\n`,
@@ -283,7 +286,7 @@ async function runAuthSubcommand(
   }
 
   if (verb === "check") {
-    const res = await impl.checkMcpLogin(gw, { mcpId });
+    const res = await checkMcpLogin(gw, { mcpId });
     const text = extractText(res.content);
     const parsed = tryJson(text);
     if (parsed?.authenticated === true) {
@@ -297,7 +300,7 @@ async function runAuthSubcommand(
   }
 
   if (verb === "logout") {
-    const res = await impl.logoutMcp(gw, { mcpId });
+    const res = await logoutMcp(gw, { mcpId });
     const text = extractText(res.content);
     // Tools that required auth are now unreachable — refresh so the next
     // invocation sees the empty state.