@abot-ai/runtime 1.6.0 → 1.8.0

package/plugins/document-reader/README.md

@@ -0,0 +1,33 @@
+# Document Reader
+
+Reads bounded text from PDF, DOCX, XLSX, PPTX, TXT, CSV, MD, JSON and RTF files
+on Linux, macOS and native Windows. Sources are request attachments or files
+inside the configured agent work directory and workspace. Request-specific
+path restrictions and attachment identities retain their existing meaning.
+
+The shared limits remain 10 MiB per input file, 40,000 characters per requested
+window, and the existing archive expansion and PDF worker resource limits.
+Results describe pagination and omitted text. The reader does not execute
+document macros or modify the source.
+
+## Windows requirements
+
+The SDK reads through built-in Windows PowerShell and its C# helper. No
+Companion, WSL, Docker, elevation or execution-policy bypass is needed.
+A blocked reader returns `document_safe_read_unavailable` and instructs the
+model not to retry or bypass the restriction. Request cancellation stops the
+read and extraction. PDF and Office parsing use the same packaged libraries
+as the other platforms; no Office installation or OCR is required.
+
+PDF parsing runs in a separate Node process on Windows to keep native parser
+faults out of the Runtime. Linux/macOS retain their worker-thread boundary.
+Both use the same parser, page/text limits and 30-second deadline. Windows
+passes documents through pipes, without temporary document files, and waits
+for process exit on cancellation. The V8 old-generation limit is 128 MiB,
+young-generation at most 16 MiB (4 MiB semi-spaces), and stack 4 MiB. These
+are JavaScript engine limits, not a cap on native allocations. Explicit Node CLI flags enforce the heap and stack limits; operator-provided
+Node configuration remains inherited.
+
+If Windows cannot start or stop the PDF process, the tool returns
+`document_pdf_process_unavailable` and asks the model not to retry or bypass
+the restriction.

package/plugins/document-reader/plugin.json

@@ -4,6 +4,7 @@
   "version": "0.1.0",
   "description": "Extract bounded text from PDF, Office and supported text documents. Use file readers for source code.",
   "extensions": {
+    "ai.abot.compatibility": { "version": 1, "runtimePlatforms": ["linux", "darwin", "win32"] },
     "ai.abot.runtime": {
       "version": 1,
       "entrypoint": "./src/index.cjs",
@@ -42,6 +43,7 @@
           "operations": {
             "read_document": {
               "summary": "Extract document text, not source code. For .js, .ts, .html, .css and other code files, use read_one_file or inspect_target when available. Accepts only PDF, DOCX, XLSX, PPTX, TXT, CSV, MD, JSON and RTF; returns one bounded character window.",
+              "outputChannels": {"text": "content", "data": "metadata"},
               "attachmentInput": {
                 "param": "source",
                 "acceptedMimeTypes": [

package/plugins/document-reader/source/pdf-contract.ts

@@ -0,0 +1,57 @@
+import {
+  MAX_PDF_PAGES,
+  MAX_RETAINED_TEXT_CHARS,
+  PDF_EXTRACTION_TIMEOUT_MS,
+  PDF_MAX_OLD_GENERATION_MB,
+  PDF_MAX_STACK_MB,
+  PDF_MAX_YOUNG_GENERATION_MB,
+  PDF_PAGE_BATCH_SIZE,
+} from "./constants.js";
+
+export type PdfExtractionLimits = Readonly<{
+  maxPages: number;
+  pageBatchSize: number;
+  maxRetainedCharacters: number;
+  timeoutMs: number;
+  maxOldGenerationSizeMb: number;
+  maxYoungGenerationSizeMb: number;
+  stackSizeMb: number;
+}>;
+
+export const PDF_EXTRACTION_LIMITS: PdfExtractionLimits = Object.freeze({
+  maxPages: MAX_PDF_PAGES,
+  pageBatchSize: PDF_PAGE_BATCH_SIZE,
+  maxRetainedCharacters: MAX_RETAINED_TEXT_CHARS,
+  timeoutMs: PDF_EXTRACTION_TIMEOUT_MS,
+  maxOldGenerationSizeMb: PDF_MAX_OLD_GENERATION_MB,
+  maxYoungGenerationSizeMb: PDF_MAX_YOUNG_GENERATION_MB,
+  stackSizeMb: PDF_MAX_STACK_MB,
+});
+
+type PdfWorkerSuccess = Readonly<{
+  kind: "success";
+  text: string;
+  totalCharacters: number;
+  returnedCharacters: number;
+  totalPages: number;
+  processedPages: number;
+}>;
+
+type PdfWorkerFailure = Readonly<{
+  kind: "failure";
+  code?: string;
+  message: string;
+}>;
+
+export type PdfWorkerMessage = PdfWorkerSuccess | PdfWorkerFailure;
+
+export type PdfParserInput = Readonly<{
+  bytes: ArrayBuffer | Uint8Array;
+  pdfParseEntrypoint: string;
+  limits: Readonly<{
+    maxPages: number;
+    pageBatchSize: number;
+    maxRetainedCharacters: number;
+    maxErrorMessageCharacters: number;
+  }>;
+}>;

package/plugins/document-reader/source/pdf-parser.ts

@@ -0,0 +1,139 @@
+import type { PdfParserInput, PdfWorkerMessage } from "./pdf-contract.js";
+
+// Serialized into the isolated parser. Keep runtime dependencies inside this function.
+export async function runPdfParser(
+  data: PdfParserInput,
+  publish: (message: PdfWorkerMessage) => void,
+): Promise<void> {
+  const fail = (code: string, message: string): never => {
+    const error = new Error(message) as Error & { code: string };
+    error.code = code;
+    throw error;
+  };
+
+  const boundedMessage = (value: unknown): string => {
+    const message = value instanceof Error ? value.message : String(value);
+    return message.slice(0, data.limits.maxErrorMessageCharacters);
+  };
+
+  let parser:
+    | InstanceType<(typeof import("pdf-parse"))["PDFParse"]>
+    | undefined;
+  try {
+    const { PDFParse } = require(
+      data.pdfParseEntrypoint,
+    ) as typeof import("pdf-parse");
+    parser = new PDFParse({
+      data: new Uint8Array(data.bytes),
+      isEvalSupported: false,
+      stopAtErrors: true,
+    });
+    const info = await parser.getInfo();
+    const totalPages = info.total;
+    if (!Number.isSafeInteger(totalPages) || totalPages < 0) {
+      fail("document_content_invalid", "The PDF page index is invalid.");
+    }
+    if (totalPages > data.limits.maxPages) {
+      fail(
+        "document_pdf_page_limit",
+        `The PDF exceeds the ${data.limits.maxPages}-page parsing limit.`,
+      );
+    }
+
+    const retainedParts: string[] = [];
+    let retainedCharacters = 0;
+    let totalCharacters = 0;
+    let processedPages = 0;
+    let hasContent = false;
+
+    const append = (rawValue: string): void => {
+      const value = rawValue.replaceAll("\u0000", "").trim();
+      if (value.length === 0) return;
+      const separator = hasContent ? "\n\n" : "";
+      hasContent = true;
+      const nextTotal = totalCharacters + separator.length + value.length;
+      if (!Number.isSafeInteger(nextTotal)) {
+        fail(
+          "document_pdf_resource_limit",
+          "The PDF text exceeds the supported character range.",
+        );
+      }
+      totalCharacters = nextTotal;
+      let remaining = data.limits.maxRetainedCharacters - retainedCharacters;
+      if (remaining <= 0) return;
+      if (separator.length > 0) {
+        const retainedSeparator = separator.slice(0, remaining);
+        retainedParts.push(retainedSeparator);
+        retainedCharacters += retainedSeparator.length;
+        remaining -= retainedSeparator.length;
+      }
+      if (remaining > 0) {
+        const retainedValue = value.slice(0, remaining);
+        retainedParts.push(retainedValue);
+        retainedCharacters += retainedValue.length;
+      }
+    };
+
+    for (
+      let firstPage = 1;
+      firstPage <= totalPages;
+      firstPage += data.limits.pageBatchSize
+    ) {
+      const pageNumbers = Array.from(
+        {
+          length: Math.min(
+            data.limits.pageBatchSize,
+            totalPages - firstPage + 1,
+          ),
+        },
+        (_, index) => firstPage + index,
+      );
+      const batch = await parser.getText({
+        partial: pageNumbers,
+        pageJoiner: "",
+      });
+      if (!Array.isArray(batch.pages)) {
+        fail(
+          "document_content_invalid",
+          "The PDF page set could not be extracted.",
+        );
+      }
+      for (const page of batch.pages) {
+        if (typeof page?.text !== "string") {
+          fail("document_content_invalid", "The PDF page text is invalid.");
+        }
+        processedPages += 1;
+        append(page.text);
+      }
+    }
+    if (processedPages !== totalPages) {
+      fail(
+        "document_content_invalid",
+        "The PDF page set could not be extracted completely.",
+      );
+    }
+    publish({
+      kind: "success",
+      text: retainedParts.join(""),
+      totalCharacters,
+      returnedCharacters: retainedCharacters,
+      totalPages,
+      processedPages,
+    } satisfies Extract<PdfWorkerMessage, { kind: "success" }>);
+  } catch (error) {
+    const candidateCode =
+      error instanceof Error &&
+      typeof (error as Error & { code?: unknown }).code === "string"
+        ? (error as Error & { code: string }).code
+        : undefined;
+    publish({
+      kind: "failure",
+      ...(candidateCode ? { code: candidateCode } : {}),
+      message: boundedMessage(error),
+    } satisfies Extract<PdfWorkerMessage, { kind: "failure" }>);
+  } finally {
+    if (parser) {
+      await parser.destroy().catch(() => undefined);
+    }
+  }
+}

package/plugins/document-reader/source/pdf-process-main.ts

@@ -0,0 +1,56 @@
+import type { PdfParserInput, PdfWorkerMessage } from "./pdf-contract.js";
+import type { runPdfParser } from "./pdf-parser.js";
+
+export const PDF_PROCESS_HEADER_MAX_BYTES = 64 * 1024;
+
+// Serialized into a fresh Node process; no imports from the host are evaluated there.
+export async function pdfProcessMain(
+  parse: typeof runPdfParser,
+  maxInputBytes: number,
+  maxHeaderBytes: number,
+  maxHeapBytes: number,
+): Promise<void> {
+  // Parser diagnostics are not part of the result protocol or user-visible evidence.
+  console.log = console.warn = console.error = () => undefined;
+  try {
+    const { heap_size_limit } = require("node:v8").getHeapStatistics();
+    if (heap_size_limit > maxHeapBytes) {
+      const failure: PdfWorkerMessage = {
+        kind: "failure",
+        code: "document_pdf_resource_limit",
+        message: "PDF extraction could not establish its memory limit.",
+      };
+      process.stdout.end(JSON.stringify(failure), () => process.exit(0));
+      return;
+    }
+    const chunks: Buffer[] = [];
+    let size = 0;
+    for await (const chunk of process.stdin) {
+      size += chunk.length;
+      if (size > maxInputBytes + maxHeaderBytes + 1) {
+        throw new Error("PDF process input exceeds its limit.");
+      }
+      chunks.push(chunk);
+    }
+    const input = Buffer.concat(chunks, size);
+    const separator = input.indexOf(10);
+    if (separator < 0) throw new Error("Missing PDF process header.");
+    if (separator > maxHeaderBytes)
+      throw new Error("PDF process header is too large.");
+    const bytes = input.subarray(separator + 1);
+    if (bytes.length > maxInputBytes)
+      throw new Error("PDF process input is too large.");
+    const header = JSON.parse(
+      input.subarray(0, separator).toString("utf8"),
+    ) as Omit<PdfParserInput, "bytes">;
+    let result: PdfWorkerMessage | undefined;
+    await parse({ ...header, bytes }, (message) => {
+      result = message;
+    });
+    if (!result) throw new Error("PDF parser returned no result.");
+    process.stdout.end(JSON.stringify(result), () => process.exit(0));
+  } catch {
+    // The parent reports a bounded failure; document bytes and native diagnostics stay private.
+    process.exit(1);
+  }
+}

package/plugins/document-reader/source/pdf-process.ts

@@ -0,0 +1,207 @@
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import {
+  MAX_DOCUMENT_BYTES,
+  MAX_PDF_ERROR_MESSAGE_CHARS,
+} from "./constants.js";
+import { DocumentReaderError } from "./errors.js";
+import {
+  PDF_EXTRACTION_LIMITS,
+  type PdfExtractionLimits,
+} from "./pdf-contract.js";
+import { runPdfParser } from "./pdf-parser.js";
+import {
+  PDF_PROCESS_HEADER_MAX_BYTES,
+  pdfProcessMain,
+} from "./pdf-process-main.js";
+import { documentFromPdfMessage } from "./pdf-result.js";
+import type { ExtractedDocument } from "./types.js";
+
+function pdfSemiSpaceLimitMb(youngGenerationMb: number): number {
+  // V8 rounds semi-spaces up to a power of two. Choose a lower power so its
+  // three-space young generation stays within the declared memory budget.
+  const maximum = Math.floor(youngGenerationMb / 3);
+  let size = 1;
+  while (size * 2 <= maximum) size *= 2;
+  return size;
+}
+
+function pdfProcessArguments(limits: PdfExtractionLimits): string[] {
+  return [
+    "--input-type=commonjs",
+    "--max-old-space-size=" + limits.maxOldGenerationSizeMb,
+    // V8's young generation uses three semi-spaces; keep it within the existing bound.
+    "--max-semi-space-size=" +
+      pdfSemiSpaceLimitMb(limits.maxYoungGenerationSizeMb),
+    "--stack-size=" + Math.floor(limits.stackSizeMb * 1024),
+    "--eval",
+    "(" +
+      pdfProcessMain.toString() +
+      ")(" +
+      runPdfParser.toString() +
+      ", " +
+      MAX_DOCUMENT_BYTES +
+      ", " +
+      PDF_PROCESS_HEADER_MAX_BYTES +
+      ", " +
+      (limits.maxOldGenerationSizeMb + limits.maxYoungGenerationSizeMb) *
+        1024 *
+        1024 +
+      ")",
+  ];
+}
+
+export function createPdfExtractionProcess(
+  bytes: Uint8Array,
+  pdfParseEntrypoint: string,
+  limits: PdfExtractionLimits,
+): ChildProcessWithoutNullStreams {
+  const header = Buffer.from(
+    JSON.stringify({
+      pdfParseEntrypoint,
+      limits: {
+        maxPages: limits.maxPages,
+        pageBatchSize: limits.pageBatchSize,
+        maxRetainedCharacters: limits.maxRetainedCharacters,
+        maxErrorMessageCharacters: MAX_PDF_ERROR_MESSAGE_CHARS,
+      },
+    }) + "\n",
+  );
+  if (header.length > PDF_PROCESS_HEADER_MAX_BYTES) {
+    throw new Error("PDF process header exceeds its limit.");
+  }
+  const child = spawn(process.execPath, pdfProcessArguments(limits), {
+    windowsHide: true,
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+  child.stdin.write(header);
+  child.stdin.end(Buffer.from(bytes));
+  return child;
+}
+
+function pdfCancellationError(): DocumentReaderError {
+  return new DocumentReaderError(
+    "document_read_cancelled",
+    "Document reading was cancelled.",
+  );
+}
+
+function pdfResourceError(message: string): DocumentReaderError {
+  return new DocumentReaderError("document_pdf_resource_limit", message);
+}
+
+function didPdfProcessExitCleanly(
+  code: number | null,
+  signal: NodeJS.Signals | null,
+): boolean {
+  if (signal !== null) return false;
+  return code === 0;
+}
+
+export async function extractPdfInProcess(
+  bytes: Uint8Array,
+  params: Readonly<{
+    pdfParseEntrypoint: string;
+    signal?: AbortSignal;
+    limits?: PdfExtractionLimits;
+  }>,
+): Promise<ExtractedDocument> {
+  if (params.signal?.aborted) throw pdfCancellationError();
+  if (bytes.byteLength > MAX_DOCUMENT_BYTES) {
+    throw new DocumentReaderError(
+      "document_file_too_large",
+      "The PDF exceeds the input size limit.",
+    );
+  }
+  const limits = params.limits ?? PDF_EXTRACTION_LIMITS;
+  const child = createPdfExtractionProcess(
+    bytes,
+    params.pdfParseEntrypoint,
+    limits,
+  );
+  // A JSON string can use six bytes per UTF-16 code unit, plus fixed metadata.
+  const maxResultBytes = limits.maxRetainedCharacters * 6 + 4096;
+  return new Promise<ExtractedDocument>((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let resultBytes = 0;
+    let failure: Error | undefined;
+    const stopPdfProcess = (error: Error): void => {
+      if (failure) return;
+      failure = error;
+      chunks.length = 0;
+      child.stdin.destroy();
+      child.kill("SIGKILL");
+    };
+    const onAbort = (): void => stopPdfProcess(pdfCancellationError());
+    const timeout = setTimeout(
+      () =>
+        stopPdfProcess(
+          pdfResourceError(
+            "PDF extraction exceeded the " +
+              limits.timeoutMs +
+              "-millisecond time limit.",
+          ),
+        ),
+      limits.timeoutMs,
+    );
+    timeout.unref();
+    child.stdout.on("data", (chunk: Buffer) => {
+      if (failure) return;
+      resultBytes += chunk.length;
+      if (resultBytes > maxResultBytes) {
+        stopPdfProcess(
+          pdfResourceError("PDF extraction exceeded its result size limit."),
+        );
+        return;
+      }
+      chunks.push(chunk);
+    });
+    child.stderr.resume();
+    child.stdin.on("error", () =>
+      stopPdfProcess(
+        new Error("PDF extraction process could not receive its input."),
+      ),
+    );
+    child.stdout.on("error", () =>
+      stopPdfProcess(
+        new Error("PDF extraction process could not return its result."),
+      ),
+    );
+    child.stderr.on("error", () =>
+      stopPdfProcess(new Error("PDF extraction process stream failed.")),
+    );
+    child.on("error", () =>
+      stopPdfProcess(
+        new DocumentReaderError(
+          "document_pdf_process_unavailable",
+          "The PDF extraction process could not be started or stopped. Do not retry or bypass this restriction with another tool; ask the user to check system requirements or contact their administrator.",
+        ),
+      ),
+    );
+    child.once("close", (code, signal) => {
+      clearTimeout(timeout);
+      params.signal?.removeEventListener("abort", onAbort);
+      if (failure) {
+        reject(failure);
+        return;
+      }
+      if (!didPdfProcessExitCleanly(code, signal)) {
+        reject(new Error("PDF extraction process stopped unexpectedly."));
+        return;
+      }
+      try {
+        const message: unknown = JSON.parse(
+          Buffer.concat(chunks, resultBytes).toString("utf8"),
+        );
+        resolve(documentFromPdfMessage(message, limits));
+      } catch (error) {
+        if (error instanceof SyntaxError) {
+          reject(new Error("PDF extraction process returned invalid data."));
+          return;
+        }
+        reject(error);
+      }
+    });
+    params.signal?.addEventListener("abort", onAbort, { once: true });
+    if (params.signal?.aborted) onAbort();
+  });
+}

package/plugins/document-reader/source/pdf-result.ts

@@ -0,0 +1,79 @@
+import { MAX_PDF_ERROR_MESSAGE_CHARS } from "./constants.js";
+import { DocumentReaderError } from "./errors.js";
+import type { PdfExtractionLimits, PdfWorkerMessage } from "./pdf-contract.js";
+import type { ExtractedDocument } from "./types.js";
+
+const CONTROLLED_PDF_ERROR_CODES = new Set([
+  "document_content_invalid",
+  "document_pdf_page_limit",
+  "document_pdf_resource_limit",
+]);
+
+function isSafeNonNegativeInteger(value: unknown): value is number {
+  return Number.isSafeInteger(value) && typeof value === "number" && value >= 0;
+}
+
+function isPdfWorkerMessage(value: unknown): value is PdfWorkerMessage {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as Partial<PdfWorkerMessage>;
+  if (candidate.kind === "failure") {
+    return (
+      typeof candidate.message === "string" &&
+      candidate.message.length <= MAX_PDF_ERROR_MESSAGE_CHARS &&
+      (candidate.code === undefined || typeof candidate.code === "string")
+    );
+  }
+  return (
+    candidate.kind === "success" &&
+    typeof candidate.text === "string" &&
+    isSafeNonNegativeInteger(candidate.totalCharacters) &&
+    isSafeNonNegativeInteger(candidate.returnedCharacters) &&
+    isSafeNonNegativeInteger(candidate.totalPages) &&
+    isSafeNonNegativeInteger(candidate.processedPages)
+  );
+}
+
+function isBoundedPdfSuccess(
+  message: Extract<PdfWorkerMessage, { kind: "success" }>,
+  limits: PdfExtractionLimits,
+): boolean {
+  if (message.text.length !== message.returnedCharacters) return false;
+  if (message.returnedCharacters > limits.maxRetainedCharacters) return false;
+  if (message.returnedCharacters > message.totalCharacters) return false;
+  if (message.totalPages > limits.maxPages) return false;
+  return message.processedPages === message.totalPages;
+}
+
+export function documentFromPdfMessage(
+  message: unknown,
+  limits: PdfExtractionLimits,
+): ExtractedDocument {
+  if (!isPdfWorkerMessage(message)) {
+    throw new Error("PDF extraction worker returned invalid data.");
+  }
+  if (message.kind === "failure") {
+    if (message.code && CONTROLLED_PDF_ERROR_CODES.has(message.code)) {
+      throw new DocumentReaderError(message.code, message.message);
+    }
+    throw new Error(message.message);
+  }
+  if (!isBoundedPdfSuccess(message, limits)) {
+    throw new Error("PDF extraction worker exceeded its contract.");
+  }
+  return Object.freeze({
+    text: message.text,
+    textBounds: Object.freeze({
+      truncated: message.totalCharacters > message.returnedCharacters,
+      totalCharacters: message.totalCharacters,
+      returnedCharacters: message.returnedCharacters,
+      omittedCharacters: message.totalCharacters - message.returnedCharacters,
+      maxCharacters: limits.maxRetainedCharacters,
+    }),
+    format: Object.freeze({
+      kind: "pdf",
+      totalPages: message.totalPages,
+      processedPages: message.processedPages,
+      maxPages: limits.maxPages,
+    }),
+  });
+}