Vendor OpenClaw source as Adolf fork baseline

Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11),
free to diverge. Tree copied sans upstream .git; upstream remote added for
future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19.
Preserves docs/ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2

extensions/document-extract/document-extractor.test.ts

@@ -0,0 +1,192 @@
+// Document Extract tests cover document extractor plugin behavior.
+import { afterAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { createEngineMock, openPdfMock, pdfDocument } = vi.hoisted(() => ({
+  createEngineMock: vi.fn(),
+  openPdfMock: vi.fn(),
+  pdfDocument: {
+    pageCount: 2,
+    extract: vi.fn(),
+    destroy: vi.fn(),
+  },
+}));
+
+vi.mock("clawpdf", () => ({
+  createEngine: createEngineMock,
+}));
+
+import { createPdfDocumentExtractor } from "./document-extractor.js";
+
+function request(overrides = {}) {
+  return {
+    buffer: Buffer.from("%PDF-1.4"),
+    mimeType: "application/pdf",
+    maxPages: 2,
+    maxPixels: 100,
+    minTextChars: 10,
+    ...overrides,
+  };
+}
+
+describe("PDF document extractor", () => {
+  afterAll(() => {
+    vi.doUnmock("clawpdf");
+    vi.resetModules();
+  });
+
+  beforeEach(() => {
+    createEngineMock.mockResolvedValue({ open: openPdfMock });
+    openPdfMock.mockReset();
+    openPdfMock.mockResolvedValue(pdfDocument);
+    pdfDocument.pageCount = 2;
+    pdfDocument.extract.mockReset();
+    pdfDocument.destroy.mockReset();
+  });
+
+  it("declares PDF support", () => {
+    const extractor = createPdfDocumentExtractor();
+    const { extract, ...descriptor } = extractor;
+    expect(extract).toBeInstanceOf(Function);
+    expect(descriptor).toEqual({
+      id: "pdf",
+      label: "PDF",
+      mimeTypes: ["application/pdf"],
+      autoDetectOrder: 10,
+    });
+  });
+
+  it("extracts text first and renders each fallback page with its own pixel budget", async () => {
+    pdfDocument.extract
+      .mockResolvedValueOnce({ text: "", images: [] })
+      .mockResolvedValueOnce({
+        text: "",
+        images: [
+          {
+            type: "image",
+            bytes: Uint8Array.from(Buffer.from("png1")),
+            mimeType: "image/png",
+            page: 1,
+            width: 5,
+            height: 10,
+          },
+        ],
+      })
+      .mockResolvedValueOnce({
+        text: "",
+        images: [
+          {
+            type: "image",
+            bytes: Uint8Array.from(Buffer.from("png2")),
+            mimeType: "image/png",
+            page: 2,
+            width: 5,
+            height: 10,
+          },
+        ],
+      });
+    const extractor = createPdfDocumentExtractor();
+
+    const result = await extractor.extract(request());
+
+    if (!result) {
+      throw new Error("Expected PDF extraction result");
+    }
+    expect(openPdfMock).toHaveBeenCalledWith(expect.any(Uint8Array));
+    expect(pdfDocument.extract).toHaveBeenNthCalledWith(1, {
+      mode: "text",
+      maxPages: 2,
+      maxTextChars: 200_000,
+    });
+    // Each page renders in its own extract() call, with the aggregate pixel cap
+    // allocated across selected pages so later pages are not starved.
+    expect(pdfDocument.extract).toHaveBeenNthCalledWith(2, {
+      mode: "images",
+      pages: [1],
+      image: { maxDimension: 10_000, maxPixels: 50, forms: true },
+    });
+    expect(pdfDocument.extract).toHaveBeenNthCalledWith(3, {
+      mode: "images",
+      pages: [2],
+      image: { maxDimension: 10_000, maxPixels: 50, forms: true },
+    });
+    expect(result).toEqual({
+      text: "",
+      images: [
+        { type: "image", data: "cG5nMQ==", mimeType: "image/png" },
+        { type: "image", data: "cG5nMg==", mimeType: "image/png" },
+      ],
+    });
+    expect(pdfDocument.destroy).toHaveBeenCalledTimes(1);
+  });
+
+  it("skips image fallback when enough text is extracted", async () => {
+    pdfDocument.extract.mockResolvedValueOnce({ text: "enough text", images: [] });
+    const extractor = createPdfDocumentExtractor();
+
+    const result = await extractor.extract(request({ minTextChars: 5 }));
+
+    expect(result).toEqual({ text: "enough text", images: [] });
+    expect(pdfDocument.extract).toHaveBeenCalledTimes(1);
+    expect(pdfDocument.destroy).toHaveBeenCalledTimes(1);
+  });
+
+  it("opens encrypted PDFs with the request password", async () => {
+    pdfDocument.extract.mockResolvedValueOnce({ text: "enough text", images: [] });
+    const extractor = createPdfDocumentExtractor();
+
+    await extractor.extract(request({ password: "secret" }));
+
+    expect(openPdfMock).toHaveBeenCalledWith(expect.any(Uint8Array), { password: "secret" });
+    expect(pdfDocument.destroy).toHaveBeenCalledTimes(1);
+  });
+
+  it("normalizes clawpdf password errors", async () => {
+    openPdfMock.mockRejectedValueOnce(
+      Object.assign(new Error("bad password"), { code: "password" }),
+    );
+    const extractor = createPdfDocumentExtractor();
+
+    await expect(extractor.extract(request({ password: "wrong" }))).rejects.toThrow(
+      "PDF requires a password or password is incorrect.",
+    );
+    expect(pdfDocument.destroy).not.toHaveBeenCalled();
+  });
+
+  it("filters selected pages and renders them one page per image call", async () => {
+    pdfDocument.extract
+      .mockResolvedValueOnce({ text: "", images: [] })
+      .mockResolvedValueOnce({ text: "", images: [] })
+      .mockResolvedValueOnce({ text: "", images: [] });
+    const extractor = createPdfDocumentExtractor();
+
+    await extractor.extract(request({ pageNumbers: [3, 2, 0, 1], maxPages: 2 }));
+
+    expect(pdfDocument.extract).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ mode: "text", pages: [2, 1] }),
+    );
+    expect(pdfDocument.extract).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({ mode: "images", pages: [2] }),
+    );
+    expect(pdfDocument.extract).toHaveBeenNthCalledWith(
+      3,
+      expect.objectContaining({ mode: "images", pages: [1] }),
+    );
+  });
+
+  it("reports image fallback failures and returns extracted text", async () => {
+    const onImageExtractionError = vi.fn();
+    const failure = new Error("render failed");
+    pdfDocument.extract
+      .mockResolvedValueOnce({ text: "short", images: [] })
+      .mockRejectedValueOnce(failure);
+    const extractor = createPdfDocumentExtractor();
+
+    const result = await extractor.extract(request({ onImageExtractionError }));
+
+    expect(result).toEqual({ text: "short", images: [] });
+    expect(onImageExtractionError).toHaveBeenCalledWith(failure);
+    expect(pdfDocument.destroy).toHaveBeenCalledTimes(1);
+  });
+});

extensions/document-extract/document-extractor.ts

@@ -0,0 +1,135 @@
+// Document Extract plugin module implements document extractor behavior.
+import type { PdfDocument, PdfEngine, PdfImage } from "clawpdf";
+import type {
+  DocumentExtractedImage,
+  DocumentExtractionRequest,
+  DocumentExtractionResult,
+  DocumentExtractorPlugin,
+} from "openclaw/plugin-sdk/document-extractor";
+
+const MAX_EXTRACTED_TEXT_CHARS = 200_000;
+const MAX_RENDER_DIMENSION = 10_000;
+
+let pdfEnginePromise: Promise<PdfEngine> | null = null;
+
+async function loadPdfEngine(): Promise<PdfEngine> {
+  if (!pdfEnginePromise) {
+    pdfEnginePromise = import("clawpdf")
+      .then(({ createEngine }) => createEngine())
+      .catch((err: unknown) => {
+        pdfEnginePromise = null;
+        throw new Error("Dependency clawpdf is required for PDF extraction", {
+          cause: err,
+        });
+      });
+  }
+  return pdfEnginePromise;
+}
+
+function toDocumentImage(image: PdfImage): DocumentExtractedImage {
+  return {
+    type: "image",
+    data: Buffer.from(image.bytes).toString("base64"),
+    mimeType: image.mimeType,
+  };
+}
+
+function isPdfPasswordError(err: unknown): boolean {
+  return Boolean(err && typeof err === "object" && (err as { code?: unknown }).code === "password");
+}
+
+async function openPdfDocument(params: {
+  engine: PdfEngine;
+  input: Uint8Array;
+  password?: string;
+}): Promise<PdfDocument> {
+  try {
+    return params.password
+      ? await params.engine.open(params.input, { password: params.password })
+      : await params.engine.open(params.input);
+  } catch (err) {
+    if (isPdfPasswordError(err)) {
+      throw new Error("PDF requires a password or password is incorrect.", { cause: err });
+    }
+    throw err;
+  }
+}
+
+async function extractPdfContent(
+  request: DocumentExtractionRequest,
+): Promise<DocumentExtractionResult> {
+  const engine = await loadPdfEngine();
+  const pdf = await openPdfDocument({
+    engine,
+    input: new Uint8Array(request.buffer),
+    ...(request.password ? { password: request.password } : {}),
+  });
+  try {
+    const pages = request.pageNumbers
+      ? request.pageNumbers
+          .filter((p) => Number.isInteger(p) && p >= 1 && p <= pdf.pageCount)
+          .slice(0, request.maxPages)
+      : undefined;
+    const pageSelection = pages ? { pages } : { maxPages: request.maxPages };
+
+    const textResult = await pdf.extract({
+      mode: "text",
+      ...pageSelection,
+      maxTextChars: MAX_EXTRACTED_TEXT_CHARS,
+    });
+    const text = textResult.text;
+
+    if (text.trim().length >= request.minTextChars) {
+      return { text, images: [] };
+    }
+
+    // clawpdf's image render budget (maxPixels) is shared across every page in one
+    // extract() call: the first page consumes it and later pages collapse to 1x1
+    // PNGs that vision models reject. Render each page separately, allocating the
+    // remaining aggregate budget across pages that still need rendering.
+    const imagePages =
+      pages ?? Array.from({ length: Math.min(pdf.pageCount, request.maxPages) }, (_, i) => i + 1);
+
+    try {
+      const images: DocumentExtractedImage[] = [];
+      let remainingPixels = request.maxPixels;
+      for (let index = 0; index < imagePages.length; index += 1) {
+        if (remainingPixels <= 0) {
+          break;
+        }
+        const pagesRemaining = imagePages.length - index;
+        const maxPixelsPerPage = Math.max(1, Math.ceil(remainingPixels / pagesRemaining));
+        const pageNumber = imagePages[index];
+        const imageResult = await pdf.extract({
+          mode: "images",
+          pages: [pageNumber],
+          image: {
+            maxDimension: MAX_RENDER_DIMENSION,
+            maxPixels: maxPixelsPerPage,
+            forms: true,
+          },
+        });
+        for (const image of imageResult.images) {
+          images.push(toDocumentImage(image));
+          remainingPixels -= image.width * image.height;
+        }
+      }
+      return { text, images };
+    } catch (err) {
+      request.onImageExtractionError?.(err);
+      return { text, images: [] };
+    }
+  } finally {
+    pdf.destroy();
+  }
+}
+
+export function createPdfDocumentExtractor(): DocumentExtractorPlugin {
+  return {
+    id: "pdf",
+    label: "PDF",
+    mimeTypes: ["application/pdf"],
+    autoDetectOrder: 10,
+    extract: extractPdfContent,
+  };
+}

extensions/document-extract/index.ts

@@ -0,0 +1,12 @@
+// Document Extract plugin entrypoint registers its OpenClaw integration.
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+
+export default definePluginEntry({
+  id: "document-extract",
+  name: "Document Extraction",
+  description: "Extract text and fallback page images from local document attachments.",
+  register() {
+    // Runtime is exposed through document-extractor.ts so document hot paths can
+    // load only the narrow extractor artifact instead of the full plugin entrypoint.
+  },
+});

extensions/document-extract/openclaw.plugin.json

@@ -0,0 +1,17 @@
+{
+  "id": "document-extract",
+  "activation": {
+    "onStartup": false
+  },
+  "enabledByDefault": true,
+  "name": "Document Extraction",
+  "description": "Extract text and fallback page images from local document attachments.",
+  "contracts": {
+    "documentExtractors": ["pdf"]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

extensions/document-extract/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@openclaw/document-extract-plugin",
+  "version": "2026.6.11",
+  "private": true,
+  "description": "OpenClaw local document extraction plugin",
+  "type": "module",
+  "dependencies": {
+    "clawpdf": "0.3.0"
+  },
+  "devDependencies": {
+    "@openclaw/plugin-sdk": "workspace:*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}