@echofiles/echo-pdf 0.3.0 → 0.4.0

package/README.md

@@ -48,6 +48,13 @@ npm i -g @echofiles/echo-pdf
 echo-pdf init --service-url https://echo-pdf.echofilesai.workers.dev
 ```
 
+本地一键启动服务（daemon）：
+
+```bash
+echo-pdf dev --port 8788
+echo-pdf init --service-url http://127.0.0.1:8788
+```
+
 配置 API Key（仅保存在本机 CLI 配置，不会上报到服务端存储）：
 
 ```bash
@@ -88,6 +95,47 @@ echo-pdf mcp tools
 echo-pdf mcp call --tool file_ops --args '{"op":"list"}'
 ```
 
+### 3.1.1 纯 MCP 场景推荐流程（本地 PDF）
+
+远端 MCP server 无法直接读取你本机文件路径。推荐两步：
+
+1. 先通过 HTTP 上传本地 PDF，拿到 `fileId`
+2. 再用 MCP 工具传 `fileId` 调用
+
+示例：
+
+```bash
+curl -sS -X POST https://echo-pdf.echofilesai.workers.dev/api/files/upload \
+  -F 'file=@./input.pdf'
+
+echo-pdf mcp call --tool pdf_extract_pages --args '{"fileId":"<FILE_ID>","pages":[1]}'
+```
+
+### 3.1.2 不上传文件的 URL ingest 流程
+
+如果 PDF 已经在公网可访问，直接传 `url`：
+
+```bash
+echo-pdf mcp call --tool pdf_extract_pages --args '{
+  "url":"https://example.com/sample.pdf",
+  "pages":[1]
+}'
+```
+
+### 3.1.3 stdio MCP（支持本地文件路径）
+
+stdio 模式会把本地 `path/filePath` 自动上传为 `fileId` 后再调用远端工具。
+
+```bash
+echo-pdf mcp stdio
+```
+
+生成 Claude Desktop/Cursor 等可用的 stdio 配置片段：
+
+```bash
+echo-pdf setup add claude-desktop --mode stdio
+```
+
 ### 3.2 给客户端生成 MCP 配置片段
 
 ```bash
@@ -107,6 +155,12 @@ echo-pdf setup add json
 - `pdf_tables_to_latex`
 - `file_ops`
 
+MCP 输出策略：
+
+- `pdf_extract_pages` 在 MCP 下默认 `returnMode=url`（不传 `returnMode` 时生效）
+- MCP `text` 会对大字段做去二进制/截断，避免把大段 base64 塞进上下文
+- 二进制结果请优先使用 `resource_link` 中的下载地址
+
 ## 4. Web UI 使用
 
 打开：
@@ -139,6 +193,12 @@ curl -sS -X POST https://echo-pdf.echofilesai.workers.dev/api/files/upload \
 
 返回中会拿到 `file.id`。
 
+CLI 等价命令：
+
+```bash
+echo-pdf file upload ./sample.pdf
+```
+
 ### 5.2 提取页面图片
 
 ```bash
@@ -152,6 +212,18 @@ curl -sS -X POST https://echo-pdf.echofilesai.workers.dev/tools/call \
   }'
 ```
 
+CLI（支持直接传本地路径）：
+
+```bash
+echo-pdf call --tool pdf_extract_pages --args '{"path":"./sample.pdf","pages":[1],"returnMode":"url"}'
+```
+
+下载产物：
+
+```bash
+echo-pdf file get --file-id <FILE_ID> --out ./output.bin
+```
+
 ### 5.3 OCR
 
 ```bash
@@ -183,6 +255,7 @@ curl -sS -X POST https://echo-pdf.echofilesai.workers.dev/tools/call \
 - `agent.defaultProvider`
 - `agent.defaultModel`
 - `service.publicBaseUrl`
+- `service.fileGet.cacheTtlSeconds`
 - `service.maxPdfBytes`
 - `service.storage.maxFileBytes`
 - `service.storage.maxTotalBytes`
@@ -205,6 +278,8 @@ curl -sS -X POST https://echo-pdf.echofilesai.workers.dev/tools/call \
 - `ECHO_PDF_DEFAULT_PROVIDER`
 - `ECHO_PDF_DEFAULT_MODEL`
 - `ECHO_PDF_PUBLIC_BASE_URL`（可选，强制 artifacts 生成外部可访问绝对 URL）
+- `ECHO_PDF_FILE_GET_CACHE_TTL_SECONDS`（可选，`/api/files/get` 缓存秒数，`0` 表示 `no-store`）
+- `ECHO_PDF_FILE_GET_AUTH_HEADER` + `ECHO_PDF_FILE_GET_AUTH_ENV`（可选，启用下载端点 header 鉴权）
 - `ECHO_PDF_MCP_KEY`（可选，启用 MCP 鉴权）
 - `ECHO_PDF_WORKER_NAME`（CLI 默认 URL 推导）
 
@@ -263,3 +338,12 @@ curl -sS -X POST https://echo-pdf.echofilesai.workers.dev/tools/call \
     "arguments":{"fileId":"<FILE_ID>","pages":[1],"returnMode":"url"}
   }'
 ```
+
+### 8.4 错误码语义
+
+- 客户端输入错误返回稳定 `4xx + code`，例如：
+  - `PAGES_REQUIRED`（400）
+  - `PAGE_OUT_OF_RANGE`（400）
+  - `MISSING_FILE_INPUT`（400）
+  - `FILE_NOT_FOUND`（404）
+- 服务端故障返回 `5xx`。

package/bin/echo-pdf.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { spawn } from "node:child_process"
 import fs from "node:fs"
 import os from "node:os"
 import path from "node:path"
@@ -208,6 +209,170 @@ const buildMcpRequest = (id, method, params = {}) => ({
   params,
 })
 
+const uploadFile = async (serviceUrl, filePath) => {
+  const absPath = path.resolve(process.cwd(), filePath)
+  const bytes = fs.readFileSync(absPath)
+  const filename = path.basename(absPath)
+  const form = new FormData()
+  form.append("file", new Blob([bytes]), filename)
+  const response = await fetch(`${serviceUrl}/api/files/upload`, { method: "POST", body: form })
+  const text = await response.text()
+  let data
+  try {
+    data = JSON.parse(text)
+  } catch {
+    data = { raw: text }
+  }
+  if (!response.ok) {
+    throw new Error(`${response.status} ${JSON.stringify(data)}`)
+  }
+  return data
+}
+
+const downloadFile = async (serviceUrl, fileId, outputPath) => {
+  const response = await fetch(`${serviceUrl}/api/files/get?fileId=${encodeURIComponent(fileId)}&download=1`)
+  if (!response.ok) {
+    const text = await response.text()
+    throw new Error(`${response.status} ${text}`)
+  }
+  const bytes = Buffer.from(await response.arrayBuffer())
+  const absOut = path.resolve(process.cwd(), outputPath)
+  fs.mkdirSync(path.dirname(absOut), { recursive: true })
+  fs.writeFileSync(absOut, bytes)
+  return absOut
+}
+
+const withUploadedLocalFile = async (serviceUrl, tool, args) => {
+  const nextArgs = { ...(args || {}) }
+  if (tool.startsWith("pdf_")) {
+    const localPath = typeof nextArgs.path === "string"
+      ? nextArgs.path
+      : (typeof nextArgs.filePath === "string" ? nextArgs.filePath : "")
+    if (localPath && !nextArgs.fileId && !nextArgs.url && !nextArgs.base64) {
+      const upload = await uploadFile(serviceUrl, localPath)
+      const fileId = upload?.file?.id
+      if (!fileId) throw new Error(`upload failed for local path: ${localPath}`)
+      nextArgs.fileId = fileId
+      delete nextArgs.path
+      delete nextArgs.filePath
+    }
+  }
+  return nextArgs
+}
+
+const runDevServer = (port, host) => {
+  const wranglerBin = path.resolve(__dirname, "../node_modules/.bin/wrangler")
+  const wranglerArgs = ["dev", "--port", String(port), "--ip", host]
+  const cmd = fs.existsSync(wranglerBin) ? wranglerBin : "npx"
+  const args = fs.existsSync(wranglerBin) ? wranglerArgs : ["-y", "wrangler", ...wranglerArgs]
+  const child = spawn(cmd, args, {
+    stdio: "inherit",
+    env: process.env,
+    cwd: process.cwd(),
+  })
+  child.on("exit", (code, signal) => {
+    if (signal) process.kill(process.pid, signal)
+    process.exit(code ?? 0)
+  })
+}
+
+const mcpReadLoop = (onMessage, onError) => {
+  let buffer = Buffer.alloc(0)
+  let expectedLength = null
+  process.stdin.on("data", (chunk) => {
+    buffer = Buffer.concat([buffer, chunk])
+    while (true) {
+      if (expectedLength === null) {
+        const headerEnd = buffer.indexOf("\r\n\r\n")
+        if (headerEnd === -1) break
+        const headerRaw = buffer.slice(0, headerEnd).toString("utf-8")
+        const lines = headerRaw.split("\r\n")
+        const cl = lines.find((line) => line.toLowerCase().startsWith("content-length:"))
+        if (!cl) {
+          onError(new Error("Missing Content-Length"))
+          buffer = buffer.slice(headerEnd + 4)
+          continue
+        }
+        expectedLength = Number(cl.split(":")[1]?.trim() || "0")
+        buffer = buffer.slice(headerEnd + 4)
+      }
+      if (!Number.isFinite(expectedLength) || expectedLength < 0) {
+        onError(new Error("Invalid Content-Length"))
+        expectedLength = null
+        continue
+      }
+      if (buffer.length < expectedLength) break
+      const body = buffer.slice(0, expectedLength).toString("utf-8")
+      buffer = buffer.slice(expectedLength)
+      expectedLength = null
+      try {
+        const maybePromise = onMessage(JSON.parse(body))
+        if (maybePromise && typeof maybePromise.then === "function") {
+          maybePromise.catch(onError)
+        }
+      } catch (error) {
+        onError(error)
+      }
+    }
+  })
+}
+
+const mcpWrite = (obj) => {
+  const body = Buffer.from(JSON.stringify(obj))
+  const header = Buffer.from(`Content-Length: ${body.length}\r\n\r\n`)
+  process.stdout.write(header)
+  process.stdout.write(body)
+}
+
+const runMcpStdio = async () => {
+  const config = loadConfig()
+  const serviceUrl = config.serviceUrl
+  const headers = buildMcpHeaders()
+  mcpReadLoop(async (msg) => {
+    const method = msg?.method
+    const id = Object.hasOwn(msg || {}, "id") ? msg.id : null
+    if (msg?.jsonrpc !== "2.0" || typeof method !== "string") {
+      mcpWrite({ jsonrpc: "2.0", id, error: { code: -32600, message: "Invalid Request" } })
+      return
+    }
+    if (method === "notifications/initialized") return
+    if (method === "initialize" || method === "tools/list") {
+      const data = await postJson(`${serviceUrl}/mcp`, msg, headers)
+      mcpWrite(data)
+      return
+    }
+    if (method === "tools/call") {
+      try {
+        const tool = String(msg?.params?.name || "")
+        const args = (msg?.params?.arguments && typeof msg.params.arguments === "object")
+          ? msg.params.arguments
+          : {}
+        const preparedArgs = await withUploadedLocalFile(serviceUrl, tool, args)
+        const payload = {
+          ...msg,
+          params: {
+            ...(msg.params || {}),
+            arguments: preparedArgs,
+          },
+        }
+        const data = await postJson(`${serviceUrl}/mcp`, payload, headers)
+        mcpWrite(data)
+      } catch (error) {
+        mcpWrite({
+          jsonrpc: "2.0",
+          id,
+          error: { code: -32603, message: error instanceof Error ? error.message : String(error) },
+        })
+      }
+      return
+    }
+    const data = await postJson(`${serviceUrl}/mcp`, msg, headers)
+    mcpWrite(data)
+  }, (error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+  })
+}
+
 const parseConfigValue = (raw, type = "auto") => {
   if (type === "string") return String(raw)
   if (type === "number") {
@@ -302,6 +467,7 @@ const usage = () => {
   process.stdout.write(`echo-pdf CLI\n\n`)
   process.stdout.write(`Commands:\n`)
   process.stdout.write(`  init [--service-url URL]\n`)
+  process.stdout.write(`  dev [--port 8788] [--host 127.0.0.1]\n`)
   process.stdout.write(`  provider set --provider <${PROVIDER_SET_NAMES.join("|")}> --api-key <KEY> [--profile name]\n`)
   process.stdout.write(`  provider use --provider <${PROVIDER_ALIASES.join("|")}> [--profile name]\n`)
   process.stdout.write(`  provider list [--profile name]\n`)
@@ -312,13 +478,29 @@ const usage = () => {
   process.stdout.write(`  model list [--profile name]\n`)
   process.stdout.write(`  tools\n`)
   process.stdout.write(`  call --tool <name> --args '<json>' [--provider alias] [--model model] [--profile name]\n`)
+  process.stdout.write(`  file upload <local.pdf>\n`)
+  process.stdout.write(`  file get --file-id <id> --out <path>\n`)
   process.stdout.write(`  mcp initialize\n`)
   process.stdout.write(`  mcp tools\n`)
   process.stdout.write(`  mcp call --tool <name> --args '<json>'\n`)
+  process.stdout.write(`  mcp stdio\n`)
   process.stdout.write(`  setup add <claude-desktop|claude-code|cursor|cline|windsurf|gemini|json>\n`)
 }
 
-const setupSnippet = (tool, serviceUrl) => {
+const setupSnippet = (tool, serviceUrl, mode = "http") => {
+  if (mode === "stdio") {
+    return {
+      mcpServers: {
+        "echo-pdf": {
+          command: "echo-pdf",
+          args: ["mcp", "stdio"],
+          env: {
+            ECHO_PDF_SERVICE_URL: serviceUrl,
+          },
+        },
+      },
+    }
+  }
   const transport = {
     type: "streamable-http",
     url: `${serviceUrl}/mcp`,
@@ -405,6 +587,14 @@ const main = async () => {
     return
   }
 
+  if (command === "dev") {
+    const port = typeof flags.port === "string" ? Number(flags.port) : 8788
+    const host = typeof flags.host === "string" ? flags.host : "127.0.0.1"
+    if (!Number.isFinite(port) || port <= 0) throw new Error("dev --port must be positive number")
+    runDevServer(Math.floor(port), host)
+    return
+  }
+
   if (command === "provider" && subcommand === "set") {
     const providerAlias = resolveProviderAliasInput(flags.provider)
     const apiKey = flags["api-key"]
@@ -538,15 +728,42 @@ const main = async () => {
     const tool = flags.tool
     if (typeof tool !== "string") throw new Error("call requires --tool")
     const args = typeof flags.args === "string" ? JSON.parse(flags.args) : {}
+    const preparedArgs = await withUploadedLocalFile(config.serviceUrl, tool, args)
     const provider = resolveProviderAlias(profile, flags.provider)
     const model = typeof flags.model === "string" ? flags.model : resolveDefaultModel(profile, provider)
     const providerApiKeys = buildProviderApiKeys(config, profileName)
-    const payload = buildToolCallRequest({ tool, args, provider, model, providerApiKeys })
+    const payload = buildToolCallRequest({ tool, args: preparedArgs, provider, model, providerApiKeys })
     const data = await postJson(`${config.serviceUrl}/tools/call`, payload)
     print(data)
     return
   }
 
+  if (command === "file") {
+    const action = rest[0] || ""
+    const config = loadConfig()
+    if (action === "upload") {
+      const filePath = rest[1]
+      if (!filePath) throw new Error("file upload requires a path")
+      const data = await uploadFile(config.serviceUrl, filePath)
+      print({
+        fileId: data?.file?.id || "",
+        filename: data?.file?.filename || path.basename(filePath),
+        sizeBytes: data?.file?.sizeBytes || 0,
+        file: data?.file || null,
+      })
+      return
+    }
+    if (action === "get") {
+      const fileId = typeof flags["file-id"] === "string" ? flags["file-id"] : ""
+      const out = typeof flags.out === "string" ? flags.out : ""
+      if (!fileId || !out) throw new Error("file get requires --file-id and --out")
+      const savedTo = await downloadFile(config.serviceUrl, fileId, out)
+      print({ ok: true, fileId, savedTo })
+      return
+    }
+    throw new Error("file command supports: upload|get")
+  }
+
   if (command === "mcp" && subcommand === "initialize") {
     const config = loadConfig()
     const data = await postJson(`${config.serviceUrl}/mcp`, buildMcpRequest(1, "initialize"), buildMcpHeaders())
@@ -575,11 +792,18 @@ const main = async () => {
     return
   }
 
+  if (command === "mcp" && subcommand === "stdio") {
+    await runMcpStdio()
+    return
+  }
+
   if (command === "setup" && subcommand === "add") {
     const tool = rest[0]
     if (!tool) throw new Error("setup add requires tool name")
     const config = loadConfig()
-    print(setupSnippet(tool, config.serviceUrl))
+    const mode = typeof flags.mode === "string" ? flags.mode : "http"
+    if (!["http", "stdio"].includes(mode)) throw new Error("setup add --mode must be http|stdio")
+    print(setupSnippet(tool, config.serviceUrl, mode))
     return
   }
 

package/echo-pdf.config.json

@@ -2,6 +2,9 @@
   "service": {
     "name": "echo-pdf",
     "publicBaseUrl": "https://echo-pdf.echofilesai.workers.dev",
+    "fileGet": {
+      "cacheTtlSeconds": 300
+    },
     "maxPdfBytes": 10000000,
     "maxPagesPerRequest": 20,
     "defaultRenderScale": 2,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@echofiles/echo-pdf",
   "description": "MCP-first PDF agent on Cloudflare Workers with CLI and web demo.",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "publishConfig": {
     "access": "public"

package/src/http-error.ts

@@ -0,0 +1,21 @@
+export class HttpError extends Error {
+  readonly status: number
+  readonly code: string
+  readonly details?: unknown
+
+  constructor(status: number, code: string, message: string, details?: unknown) {
+    super(message)
+    this.status = status
+    this.code = code
+    this.details = details
+  }
+}
+
+export const badRequest = (code: string, message: string, details?: unknown): HttpError =>
+  new HttpError(400, code, message, details)
+
+export const notFound = (code: string, message: string, details?: unknown): HttpError =>
+  new HttpError(404, code, message, details)
+
+export const unprocessable = (code: string, message: string, details?: unknown): HttpError =>
+  new HttpError(422, code, message, details)

package/src/index.ts

@@ -61,6 +61,21 @@ const asObj = (value: unknown): JsonObject =>
 const resolvePublicBaseUrl = (request: Request, configured?: string): string =>
   typeof configured === "string" && configured.length > 0 ? configured : request.url
 
+const sanitizeDownloadFilename = (filename: string): string => {
+  const cleaned = filename
+    .replace(/[\r\n"]/g, "")
+    .replace(/[^\x20-\x7E]+/g, "")
+    .trim()
+  return cleaned.length > 0 ? cleaned : "download.bin"
+}
+
+const isFileGetAuthorized = (request: Request, env: Env, config: { authHeader?: string; authEnv?: string }): boolean => {
+  if (!config.authHeader || !config.authEnv) return true
+  const required = env[config.authEnv]
+  if (typeof required !== "string" || required.length === 0) return true
+  return request.headers.get(config.authHeader) === required
+}
+
 const sseResponse = (stream: ReadableStream<Uint8Array>): Response =>
   new Response(stream, {
     headers: {
@@ -147,6 +162,10 @@ export default {
           version: config.mcp.version,
           authHeader: config.mcp.authHeader ?? null,
         },
+        fileGet: {
+          authHeader: config.service.fileGet?.authHeader ?? null,
+          cacheTtlSeconds: config.service.fileGet?.cacheTtlSeconds ?? 300,
+        },
       })
     }
 
@@ -304,6 +323,10 @@ export default {
     }
 
     if (request.method === "GET" && url.pathname === "/api/files/get") {
+      const fileGetConfig = config.service.fileGet ?? {}
+      if (!isFileGetAuthorized(request, env, fileGetConfig)) {
+        return json({ error: "Unauthorized", code: "UNAUTHORIZED" }, 401)
+      }
       const fileId = url.searchParams.get("fileId") || ""
       if (!fileId) return json({ error: "Missing fileId" }, 400)
       const file = await fileStore.get(fileId)
@@ -311,9 +334,13 @@ export default {
       const download = url.searchParams.get("download") === "1"
       const headers = new Headers()
       headers.set("Content-Type", file.mimeType)
-      headers.set("Cache-Control", "no-store")
+      const cacheTtl = Number(fileGetConfig.cacheTtlSeconds ?? 300)
+      const cacheControl = cacheTtl > 0
+        ? `public, max-age=${Math.floor(cacheTtl)}, s-maxage=${Math.floor(cacheTtl)}`
+        : "no-store"
+      headers.set("Cache-Control", cacheControl)
       if (download) {
-        headers.set("Content-Disposition", `attachment; filename=\"${file.filename.replace(/\"/g, "")}\"`)
+        headers.set("Content-Disposition", `attachment; filename=\"${sanitizeDownloadFilename(file.filename)}\"`)
       }
       return new Response(file.bytes, { status: 200, headers })
     }

package/src/mcp-server.ts

@@ -48,6 +48,16 @@ const maybeAuthorized = (request: Request, env: Env, config: EchoPdfConfig): boo
 const resolvePublicBaseUrl = (request: Request, configured?: string): string =>
   typeof configured === "string" && configured.length > 0 ? configured : request.url
 
+const prepareMcpToolArgs = (toolName: string, args: Record<string, unknown>): Record<string, unknown> => {
+  if (toolName === "pdf_extract_pages") {
+    const mode = typeof args.returnMode === "string" ? args.returnMode : ""
+    if (!mode) {
+      return { ...args, returnMode: "url" }
+    }
+  }
+  return args
+}
+
 export const handleMcpRequest = async (
   request: Request,
   env: Env,
@@ -103,7 +113,7 @@ export const handleMcpRequest = async (
   }
 
   const toolName = typeof params.name === "string" ? params.name : ""
-  const args = asObj(params.arguments)
+  const args = prepareMcpToolArgs(toolName, asObj(params.arguments))
   if (!toolName) {
     return err(id, -32602, "Invalid params: name is required", {
       code: "INVALID_PARAMS",

package/src/pdf-agent.ts

@@ -2,6 +2,7 @@ import type { Env, FileStore, ReturnMode } from "./types"
 import type { AgentTraceEvent, EchoPdfConfig, PdfOperationRequest } from "./pdf-types"
 import { resolveModelForProvider, resolveProviderAlias } from "./agent-defaults"
 import { fromBase64, normalizeReturnMode, toDataUrl } from "./file-utils"
+import { badRequest, notFound, unprocessable } from "./http-error"
 import { extractPdfPageText, getPdfPageCount, renderPdfPageToPng, toBytes } from "./pdfium-engine"
 import { visionRecognize } from "./provider-client"
 
@@ -22,11 +23,20 @@ const traceStep = (
 }
 
 const ensurePages = (pages: ReadonlyArray<number>, pageCount: number, maxPages: number): number[] => {
-  if (pages.length === 0) throw new Error("At least one page is required")
-  if (pages.length > maxPages) throw new Error(`Page count exceeds maxPagesPerRequest (${maxPages})`)
+  if (pages.length === 0) throw badRequest("PAGES_REQUIRED", "At least one page is required")
+  if (pages.length > maxPages) {
+    throw badRequest("TOO_MANY_PAGES", `Page count exceeds maxPagesPerRequest (${maxPages})`, {
+      maxPagesPerRequest: maxPages,
+      providedPages: pages.length,
+    })
+  }
   for (const page of pages) {
     if (!Number.isInteger(page) || page < 1 || page > pageCount) {
-      throw new Error(`Page ${page} out of range 1..${pageCount}`)
+      throw badRequest("PAGE_OUT_OF_RANGE", `Page ${page} out of range 1..${pageCount}`, {
+        page,
+        min: 1,
+        max: pageCount,
+      })
     }
   }
   return [...new Set(pages)].sort((a, b) => a - b)
@@ -45,7 +55,7 @@ export const ingestPdfFromPayload = async (
   if (input.fileId) {
     const existing = await opts.fileStore.get(input.fileId)
     if (!existing) {
-      throw new Error(`File not found: ${input.fileId}`)
+      throw notFound("FILE_NOT_FOUND", `File not found: ${input.fileId}`, { fileId: input.fileId })
     }
     return {
       id: existing.id,
@@ -59,7 +69,11 @@ export const ingestPdfFromPayload = async (
 
   if (input.url) {
     traceStep(opts, "start", "file.fetch.url", { url: input.url })
-    bytes = await toBytes(input.url)
+    try {
+      bytes = await toBytes(input.url)
+    } catch (error) {
+      throw badRequest("URL_FETCH_FAILED", `Unable to fetch PDF from url: ${error instanceof Error ? error.message : String(error)}`)
+    }
     try {
       const u = new URL(input.url)
       filename = decodeURIComponent(u.pathname.split("/").pop() || filename)
@@ -74,10 +88,13 @@ export const ingestPdfFromPayload = async (
   }
 
   if (!bytes) {
-    throw new Error("Missing file input. Provide fileId, url or base64")
+    throw badRequest("MISSING_FILE_INPUT", "Missing file input. Provide fileId, url or base64")
   }
   if (bytes.byteLength > config.service.maxPdfBytes) {
-    throw new Error(`PDF exceeds max size (${config.service.maxPdfBytes} bytes)`)
+    throw badRequest("PDF_TOO_LARGE", `PDF exceeds max size (${config.service.maxPdfBytes} bytes)`, {
+      maxPdfBytes: config.service.maxPdfBytes,
+      sizeBytes: bytes.byteLength,
+    })
   }
 
   const meta = await opts.fileStore.put({
@@ -164,7 +181,7 @@ export const runPdfAgent = async (
   const providerAlias = resolveProviderAlias(config, request.provider)
   const model = resolveModelForProvider(config, providerAlias, request.model)
   if (!model) {
-    throw new Error("model is required for OCR or table extraction; set agent.defaultModel")
+    throw badRequest("MODEL_REQUIRED", "model is required for OCR or table extraction; set agent.defaultModel")
   }
 
   if (request.operation === "ocr_pages") {
@@ -216,7 +233,9 @@ export const runPdfAgent = async (
     })
     const latex = extractTabularLatex(rawLatex)
     if (!latex) {
-      throw new Error(`table extraction did not return valid LaTeX tabular for page ${page}`)
+      throw unprocessable("TABLE_LATEX_MISSING", `table extraction did not return valid LaTeX tabular for page ${page}`, {
+        page,
+      })
     }
     tables.push({ page, latex })
     traceStep(opts, "end", "table.page", { page, chars: latex.length })

package/src/pdf-config.ts

@@ -37,6 +37,9 @@ const validateConfig = (config: EchoPdfConfig): EchoPdfConfig => {
   ) {
     throw new Error("service.publicBaseUrl must start with http:// or https://")
   }
+  if (typeof config.service.fileGet?.cacheTtlSeconds === "number" && config.service.fileGet.cacheTtlSeconds < 0) {
+    throw new Error("service.fileGet.cacheTtlSeconds must be >= 0")
+  }
   if (!Number.isFinite(config.service.storage.maxFileBytes) || config.service.storage.maxFileBytes <= 0) {
     throw new Error("service.storage.maxFileBytes must be positive")
   }
@@ -73,6 +76,9 @@ export const loadEchoPdfConfig = (env: Env): EchoPdfConfig => {
   const providerOverride = env.ECHO_PDF_DEFAULT_PROVIDER
   const modelOverride = env.ECHO_PDF_DEFAULT_MODEL
   const publicBaseUrlOverride = env.ECHO_PDF_PUBLIC_BASE_URL
+  const fileGetAuthHeaderOverride = env.ECHO_PDF_FILE_GET_AUTH_HEADER
+  const fileGetAuthEnvOverride = env.ECHO_PDF_FILE_GET_AUTH_ENV
+  const fileGetCacheTtlOverride = env.ECHO_PDF_FILE_GET_CACHE_TTL_SECONDS
   const withOverrides: EchoPdfConfig = {
     ...resolved,
     service: {
@@ -81,6 +87,23 @@ export const loadEchoPdfConfig = (env: Env): EchoPdfConfig => {
         typeof publicBaseUrlOverride === "string" && publicBaseUrlOverride.trim().length > 0
           ? publicBaseUrlOverride.trim()
           : resolved.service.publicBaseUrl,
+      fileGet: {
+        authHeader:
+          typeof fileGetAuthHeaderOverride === "string" && fileGetAuthHeaderOverride.trim().length > 0
+            ? fileGetAuthHeaderOverride.trim()
+            : resolved.service.fileGet?.authHeader,
+        authEnv:
+          typeof fileGetAuthEnvOverride === "string" && fileGetAuthEnvOverride.trim().length > 0
+            ? fileGetAuthEnvOverride.trim()
+            : resolved.service.fileGet?.authEnv,
+        cacheTtlSeconds: (() => {
+          if (typeof fileGetCacheTtlOverride === "string" && fileGetCacheTtlOverride.trim().length > 0) {
+            const value = Number(fileGetCacheTtlOverride)
+            return Number.isFinite(value) && value >= 0 ? Math.floor(value) : resolved.service.fileGet?.cacheTtlSeconds
+          }
+          return resolved.service.fileGet?.cacheTtlSeconds
+        })(),
+      },
     },
     agent: {
       ...resolved.agent,

package/src/pdf-types.ts

@@ -23,6 +23,11 @@ export interface EchoPdfConfig {
   readonly service: {
     readonly name: string
     readonly publicBaseUrl?: string
+    readonly fileGet?: {
+      readonly authHeader?: string
+      readonly authEnv?: string
+      readonly cacheTtlSeconds?: number
+    }
     readonly maxPdfBytes: number
     readonly maxPagesPerRequest: number
     readonly defaultRenderScale: number

package/src/r2-file-store.ts

@@ -79,20 +79,7 @@ export class R2FileStore implements FileStore {
   }
 
   async list(): Promise<ReadonlyArray<StoredFileMeta>> {
-    const listed = await this.bucket.list({ prefix: PREFIX, limit: 1000 })
-    return listed.objects.map((obj) => {
-      const meta = (obj.customMetadata ?? {}) as MetaFields
-      const createdAt = parseCreatedAt(meta.createdAt, obj.uploaded)
-      const filename = meta.filename ?? toId(obj.key)
-      const mimeType = meta.mimeType ?? obj.httpMetadata?.contentType ?? "application/octet-stream"
-      return {
-        id: toId(obj.key),
-        filename,
-        mimeType,
-        sizeBytes: obj.size,
-        createdAt,
-      }
-    })
+    return await this.listAllFiles()
   }
 
   async delete(fileId: string): Promise<boolean> {
@@ -101,7 +88,7 @@ export class R2FileStore implements FileStore {
   }
 
   async stats(): Promise<unknown> {
-    const files = await this.list()
+    const files = await this.listAllFiles()
     const totalBytes = files.reduce((sum, file) => sum + file.sizeBytes, 0)
     return {
       backend: "r2",
@@ -114,17 +101,24 @@ export class R2FileStore implements FileStore {
   }
 
   async cleanup(): Promise<unknown> {
-    const before = await this.list()
-    const deletedExpired = await this.deleteExpired(before)
-    const afterExpired = await this.list()
-    const deletedEvicted = await this.evictIfNeeded(afterExpired, 0)
-    const after = await this.list()
+    const files = await this.listAllFiles()
+    const expired = files.filter((f) => isExpired(f.createdAt, this.policy.ttlHours))
+    const active = files.filter((f) => !isExpired(f.createdAt, this.policy.ttlHours))
+    if (expired.length > 0) {
+      await this.bucket.delete(expired.map((f) => toKey(f.id)))
+    }
+    const evict = this.pickEvictions(active, 0)
+    if (evict.length > 0) {
+      await this.bucket.delete(evict.map((f) => toKey(f.id)))
+    }
+    const evictIds = new Set(evict.map((f) => f.id))
+    const after = active.filter((f) => !evictIds.has(f.id))
     const totalBytes = after.reduce((sum, file) => sum + file.sizeBytes, 0)
     return {
       backend: "r2",
       policy: this.policy,
-      deletedExpired,
-      deletedEvicted,
+      deletedExpired: expired.length,
+      deletedEvicted: evict.length,
       stats: {
         fileCount: after.length,
         totalBytes,
@@ -133,12 +127,19 @@ export class R2FileStore implements FileStore {
   }
 
   private async cleanupInternal(incomingBytes: number): Promise<void> {
-    const files = await this.list()
-    await this.deleteExpired(files)
-    const afterExpired = await this.list()
-    await this.evictIfNeeded(afterExpired, incomingBytes)
-    const finalFiles = await this.list()
-    const finalTotal = finalFiles.reduce((sum, file) => sum + file.sizeBytes, 0)
+    const files = await this.listAllFiles()
+    const expired = files.filter((f) => isExpired(f.createdAt, this.policy.ttlHours))
+    const active = files.filter((f) => !isExpired(f.createdAt, this.policy.ttlHours))
+    if (expired.length > 0) {
+      await this.bucket.delete(expired.map((f) => toKey(f.id)))
+    }
+    const evict = this.pickEvictions(active, incomingBytes)
+    if (evict.length > 0) {
+      await this.bucket.delete(evict.map((f) => toKey(f.id)))
+    }
+    const evictIds = new Set(evict.map((f) => f.id))
+    const remaining = active.filter((f) => !evictIds.has(f.id))
+    const finalTotal = remaining.reduce((sum, file) => sum + file.sizeBytes, 0)
     if (finalTotal + incomingBytes > this.policy.maxTotalBytes) {
       const err = new Error(
         `storage quota exceeded: total ${finalTotal} + incoming ${incomingBytes} > maxTotalBytes ${this.policy.maxTotalBytes}`
@@ -150,17 +151,10 @@ export class R2FileStore implements FileStore {
     }
   }
 
-  private async deleteExpired(files: ReadonlyArray<StoredFileMeta>): Promise<number> {
-    const expired = files.filter((f) => isExpired(f.createdAt, this.policy.ttlHours))
-    if (expired.length === 0) return 0
-    await this.bucket.delete(expired.map((f) => toKey(f.id)))
-    return expired.length
-  }
-
-  private async evictIfNeeded(files: ReadonlyArray<StoredFileMeta>, incomingBytes: number): Promise<number> {
+  private pickEvictions(files: ReadonlyArray<StoredFileMeta>, incomingBytes: number): StoredFileMeta[] {
     const totalBytes = files.reduce((sum, f) => sum + f.sizeBytes, 0)
     const projected = totalBytes + incomingBytes
-    if (projected <= this.policy.maxTotalBytes) return 0
+    if (projected <= this.policy.maxTotalBytes) return []
 
     const needFree = projected - this.policy.maxTotalBytes
     const candidates = [...files].sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt))
@@ -172,9 +166,30 @@ export class R2FileStore implements FileStore {
       if (freed >= needFree) break
       if (evict.length >= this.policy.cleanupBatchSize) break
     }
-    if (evict.length === 0) return 0
-    await this.bucket.delete(evict.map((f) => toKey(f.id)))
-    return evict.length
+    return evict
   }
-}
 
+  private async listAllFiles(): Promise<StoredFileMeta[]> {
+    const files: StoredFileMeta[] = []
+    let cursor: string | undefined
+    while (true) {
+      const listed = await this.bucket.list({ prefix: PREFIX, limit: 1000, cursor })
+      for (const obj of listed.objects) {
+        const meta = (obj.customMetadata ?? {}) as MetaFields
+        const createdAt = parseCreatedAt(meta.createdAt, obj.uploaded)
+        const filename = meta.filename ?? toId(obj.key)
+        const mimeType = meta.mimeType ?? obj.httpMetadata?.contentType ?? "application/octet-stream"
+        files.push({
+          id: toId(obj.key),
+          filename,
+          mimeType,
+          sizeBytes: obj.size,
+          createdAt,
+        })
+      }
+      if (listed.truncated !== true || !listed.cursor) break
+      cursor = listed.cursor
+    }
+    return files
+  }
+}

package/src/response-schema.ts

@@ -15,6 +15,10 @@ export interface ToolOutputEnvelope {
   readonly artifacts: ToolArtifact[]
 }
 
+const MAX_TEXT_STRING = 1200
+const MAX_TEXT_ARRAY = 40
+const MAX_TEXT_DEPTH = 8
+
 const asObj = (value: unknown): JsonObject =>
   typeof value === "object" && value !== null && !Array.isArray(value)
     ? (value as JsonObject)
@@ -113,6 +117,38 @@ const summarizeData = (data: unknown): string => {
   return "Tool executed successfully."
 }
 
+const sanitizeString = (value: string): string => {
+  if (value.startsWith("data:")) {
+    const [head] = value.split(",", 1)
+    return `${head},<omitted>`
+  }
+  if (/^[A-Za-z0-9+/=]{300,}$/.test(value)) {
+    return `<base64 omitted len=${value.length}>`
+  }
+  if (value.length > MAX_TEXT_STRING) {
+    return `${value.slice(0, MAX_TEXT_STRING)}...(truncated ${value.length - MAX_TEXT_STRING} chars)`
+  }
+  return value
+}
+
+const sanitizeForText = (value: unknown, depth = 0): unknown => {
+  if (depth >= MAX_TEXT_DEPTH) return "<max-depth>"
+  if (typeof value === "string") return sanitizeString(value)
+  if (typeof value !== "object" || value === null) return value
+  if (Array.isArray(value)) {
+    const items = value.slice(0, MAX_TEXT_ARRAY).map((item) => sanitizeForText(item, depth + 1))
+    if (value.length > MAX_TEXT_ARRAY) {
+      items.push(`<truncated ${value.length - MAX_TEXT_ARRAY} items>`)
+    }
+    return items
+  }
+  const out: Record<string, unknown> = {}
+  for (const [key, nested] of Object.entries(value)) {
+    out[key] = sanitizeForText(nested, depth + 1)
+  }
+  return out
+}
+
 export const buildMcpContent = (envelope: ToolOutputEnvelope): Array<Record<string, unknown>> => {
   const lines: string[] = [summarizeData(envelope.data)]
   if (envelope.artifacts.length > 0) {
@@ -130,7 +166,7 @@ export const buildMcpContent = (envelope: ToolOutputEnvelope): Array<Record<stri
     }
   }
   lines.push("")
-  lines.push(JSON.stringify(envelope, null, 2))
+  lines.push(JSON.stringify(sanitizeForText(envelope), null, 2))
 
   const content: Array<Record<string, unknown>> = [{ type: "text", text: lines.join("\n") }]
   for (const artifact of envelope.artifacts) {