@echofiles/echo-pdf 0.2.0 → 0.3.1

package/README.md

@@ -27,6 +27,13 @@
 - MCP: `https://echo-pdf.echofilesai.workers.dev/mcp`
 - HTTP API 根路径: `https://echo-pdf.echofilesai.workers.dev`
 
+## 1.1 API 兼容性说明
+
+- 从 `v0.3.0` 开始，`POST /tools/call` 返回结构改为：
+  - `{"ok": true, "data": ..., "artifacts": [...]}`
+- 老格式 `{"name":"...","output":...}` 已移除。
+- MCP `tools/call` 仍保留 `type:"text"`，并新增 `type:"resource_link"` 供下载二进制结果。
+
 ## 2. 快速开始（CLI）
 
 安装：
@@ -81,6 +88,33 @@ 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.2 给客户端生成 MCP 配置片段
 
 ```bash
@@ -100,6 +134,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 使用
 
 打开：
@@ -117,7 +157,8 @@ echo-pdf setup add json
 说明：
 
 - UI 中输入的 key 属于当前会话，不落库到服务端。
-- `returnMode` 目前仅支持 `inline` 和 `file_id`（`url` 尚未实现）。
+- `returnMode` 支持 `inline`、`file_id`、`url`。
+- `tools/call` 返回统一结构：`{ ok, data, artifacts }`，其中 `artifacts[*].url` 可直接下载。
 - 表格工具返回值会校验并要求包含合法 `tabular`，否则报错。
 
 ## 5. HTTP API 使用
@@ -174,6 +215,8 @@ 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`
@@ -184,7 +227,9 @@ curl -sS -X POST https://echo-pdf.echofilesai.workers.dev/tools/call \
 - `service.maxPdfBytes`：允许处理的 PDF 最大字节数。
 - `service.storage.maxFileBytes`：文件存储单文件上限（上传 PDF、`url/base64` ingest、以及 `file_id` 结果都会落到存储层）。
 - 当前项目要求 `service.storage.maxFileBytes >= service.maxPdfBytes`，否则配置无效并在启动时报错。
-- 默认配置下两者都是 `1200000`（约 1.2MB）。
+- 当前默认配置下两者都是 `10000000`（10MB）。
+- 当未绑定 R2、使用 DO 存储时，`service.storage.maxFileBytes` 必须 `<= 1200000`，否则启动会报错。
+- 生产建议始终绑定 R2，并让 DO 只负责协调/元数据，不承载大文件数据。
 
 常用环境变量：
 
@@ -193,6 +238,9 @@ curl -sS -X POST https://echo-pdf.echofilesai.workers.dev/tools/call \
 - `VERCEL_AI_GATEWAY_API_KEY` / `VERCEL_AI_GATEWAY_KEY`
 - `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 推导）
 
@@ -235,6 +283,28 @@ INPUT_PDF=./fixtures/input.pdf ./scripts/export-fixtures.sh
 
 当前实现要求模型输出中必须包含合法 `\\begin{tabular}...\\end{tabular}`。如果模型返回解释性文本或超时，会直接报错。
 
-### 8.3 `returnMode=url` 为什么不可用
+### 8.3 `returnMode=url` 如何使用
+
+`url` 模式会把结果落到存储层，并返回一个可直接 `GET` 的下载地址：
+
+- `GET /api/files/get?fileId=<id>`
+
+示例（提取页面并返回 URL）：
+
+```bash
+curl -sS -X POST https://echo-pdf.echofilesai.workers.dev/tools/call \
+  -H 'content-type: application/json' \
+  -d '{
+    "name":"pdf_extract_pages",
+    "arguments":{"fileId":"<FILE_ID>","pages":[1],"returnMode":"url"}
+  }'
+```
+
+### 8.4 错误码语义
 
-当前版本没有对外文件下载路由或签名 URL 能力，因此 `url` 模式未实现。请使用 `inline` 或 `file_id`。
+- 客户端输入错误返回稳定 `4xx + code`，例如：
+  - `PAGES_REQUIRED`（400）
+  - `PAGE_OUT_OF_RANGE`（400）
+  - `MISSING_FILE_INPUT`（400）
+  - `FILE_NOT_FOUND`（404）
+- 服务端故障返回 `5xx`。

package/echo-pdf.config.json

@@ -1,6 +1,10 @@
 {
   "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.2.0",
+  "version": "0.3.1",
   "type": "module",
   "publishConfig": {
     "access": "public"

package/scripts/export-fixtures.sh

@@ -41,12 +41,12 @@ run_json() {
 
 validate_ocr_json() {
   local json_file="$1"
-  node -e 'const fs=require("fs");const j=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));const pages=j?.output?.pages;if(!Array.isArray(pages)||pages.length===0)process.exit(1);const t=String(pages[0]?.text||"").trim();if(t.length===0)process.exit(1);' "$json_file"
+  node -e 'const fs=require("fs");const j=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));const pages=j?.data?.pages;if(!Array.isArray(pages)||pages.length===0)process.exit(1);const t=String(pages[0]?.text||"").trim();if(t.length===0)process.exit(1);' "$json_file"
 }
 
 validate_tables_json() {
   local json_file="$1"
-  node -e 'const fs=require("fs");const j=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));const pages=j?.output?.pages;if(!Array.isArray(pages)||pages.length===0)process.exit(1);const t=String(pages[0]?.latex||"").trim();if(t.length===0)process.exit(1);' "$json_file"
+  node -e 'const fs=require("fs");const j=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));const pages=j?.data?.pages;if(!Array.isArray(pages)||pages.length===0)process.exit(1);const t=String(pages[0]?.latex||"").trim();if(t.length===0)process.exit(1);' "$json_file"
 }
 
 # 1) Save test logs locally (do not block artifact export on transient network failure)
@@ -142,7 +142,7 @@ if [[ -n "${PROVIDER}" ]]; then
 else
   run_json "cli-extract-pages" cli call --tool pdf_extract_pages --args "{\"fileId\":\"${FILE_ID}\",\"pages\":[1],\"returnMode\":\"inline\"}"
 fi
-node -e 'const fs=require("fs");const p=process.argv[1];const out=process.argv[2];const j=JSON.parse(fs.readFileSync(p,"utf8"));const d=j.output?.images?.[0]?.data||"";if(!d.startsWith("data:image/"))process.exit(1);fs.writeFileSync(out, Buffer.from(d.split(",")[1]||"","base64"));' "${OUT_DIR}/cli-extract-pages.json" "${OUT_DIR}/page-1-cli.png"
+node -e 'const fs=require("fs");const p=process.argv[1];const out=process.argv[2];const j=JSON.parse(fs.readFileSync(p,"utf8"));const d=j.data?.images?.[0]?.data||"";if(!d.startsWith("data:image/"))process.exit(1);fs.writeFileSync(out, Buffer.from(d.split(",")[1]||"","base64"));' "${OUT_DIR}/cli-extract-pages.json" "${OUT_DIR}/page-1-cli.png"
 
 # 6) MCP tool calls
 run_json "mcp-initialize" cli mcp initialize

package/src/file-ops.ts

@@ -26,10 +26,8 @@ export const runFileOp = async (
       bytes,
     })
     const returnMode = normalizeReturnMode(input.returnMode)
-    if (returnMode === "url") {
-      throw new Error("returnMode=url is not implemented; use inline or file_id")
-    }
     if (returnMode === "file_id") return { returnMode, file: meta }
+    if (returnMode === "url") return { returnMode, file: meta, url: `/api/files/get?fileId=${encodeURIComponent(meta.id)}` }
     const stored = await fileStore.get(meta.id)
     if (!stored) throw new Error(`File not found after put: ${meta.id}`)
     return {

package/src/file-store-do.ts

@@ -276,7 +276,16 @@ export class DurableObjectFileStore {
     })
     const payload = (await response.json()) as { file?: StoredFileMeta; error?: string }
     if (!response.ok || !payload.file) {
-      throw new Error(payload.error ?? "DO put failed")
+      const details = payload as { error?: string; code?: string; policy?: unknown; stats?: unknown }
+      const error = new Error(payload.error ?? "DO put failed") as Error & {
+        status?: number
+        code?: string
+        details?: unknown
+      }
+      error.status = response.status
+      error.code = typeof details.code === "string" ? details.code : undefined
+      error.details = { policy: details.policy, stats: details.stats }
+      throw error
     }
     return payload.file
   }

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

@@ -5,6 +5,7 @@ import { handleMcpRequest } from "./mcp-server"
 import { loadEchoPdfConfig } from "./pdf-config"
 import { getRuntimeFileStore } from "./pdf-storage"
 import { listProviderModels } from "./provider-client"
+import { buildToolOutputEnvelope } from "./response-schema"
 import { callTool, listToolSchemas } from "./tool-registry"
 import type { AgentTraceEvent, PdfOperationRequest } from "./pdf-types"
 import type { Env, JsonObject } from "./types"
@@ -21,6 +22,25 @@ const json = (data: unknown, status = 200): Response =>
 const toError = (error: unknown): string =>
   error instanceof Error ? error.message : String(error)
 
+const errorStatus = (error: unknown): number | null => {
+  const status = (error as { status?: unknown })?.status
+  return typeof status === "number" && Number.isFinite(status) ? status : null
+}
+
+const errorCode = (error: unknown): string | null => {
+  const code = (error as { code?: unknown })?.code
+  return typeof code === "string" && code.length > 0 ? code : null
+}
+
+const errorDetails = (error: unknown): unknown => (error as { details?: unknown })?.details
+
+const jsonError = (error: unknown, fallbackStatus = 500): Response => {
+  const status = errorStatus(error) ?? fallbackStatus
+  const code = errorCode(error)
+  const details = errorDetails(error)
+  return json({ error: toError(error), code, details }, status)
+}
+
 const readJson = async (request: Request): Promise<Record<string, unknown>> => {
   try {
     const body = await request.json()
@@ -38,6 +58,24 @@ const asObj = (value: unknown): JsonObject =>
     ? (value as 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: {
@@ -117,13 +155,17 @@ export default {
           fileUploadEndpoint: "/api/files/upload",
           fileStatsEndpoint: "/api/files/stats",
           fileCleanupEndpoint: "/api/files/cleanup",
-          supportedReturnModes: ["inline", "file_id"],
+          supportedReturnModes: ["inline", "file_id", "url"],
         },
         mcp: {
           serverName: config.mcp.serverName,
           version: config.mcp.version,
           authHeader: config.mcp.authHeader ?? null,
         },
+        fileGet: {
+          authHeader: config.service.fileGet?.authHeader ?? null,
+          cacheTtlSeconds: config.service.fileGet?.cacheTtlSeconds ?? 300,
+        },
       })
     }
 
@@ -163,9 +205,9 @@ export default {
             ? (body.providerApiKeys as Record<string, string>)
             : undefined,
         })
-        return json({ name, output: result })
+        return json(buildToolOutputEnvelope(result, resolvePublicBaseUrl(request, config.service.publicBaseUrl)))
       } catch (error) {
-        return json({ error: toError(error) }, 500)
+        return jsonError(error, 500)
       }
     }
 
@@ -198,7 +240,7 @@ export default {
         })
         return json(result)
       } catch (error) {
-        return json({ error: toError(error) }, 500)
+        return jsonError(error, 500)
       }
     }
 
@@ -253,7 +295,7 @@ export default {
         })
         return json(result)
       } catch (error) {
-        return json({ error: toError(error) }, 500)
+        return jsonError(error, 500)
       }
     }
 
@@ -276,8 +318,31 @@ export default {
         })
         return json({ file: stored }, 200)
       } catch (error) {
-        return json({ error: toError(error) }, 500)
+        return jsonError(error, 500)
+      }
+    }
+
+    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)
+      if (!file) return json({ error: "File not found" }, 404)
+      const download = url.searchParams.get("download") === "1"
+      const headers = new Headers()
+      headers.set("Content-Type", file.mimeType)
+      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=\"${sanitizeDownloadFilename(file.filename)}\"`)
       }
+      return new Response(file.bytes, { status: 200, headers })
     }
 
     if (request.method === "GET" && url.pathname === "/api/files/stats") {
@@ -321,6 +386,7 @@ export default {
           stream: "POST /api/agent/stream",
           files: "POST /api/files/op",
           fileUpload: "POST /api/files/upload",
+          fileGet: "GET /api/files/get?fileId=<id>",
           fileStats: "GET /api/files/stats",
           fileCleanup: "POST /api/files/cleanup",
           mcp: "POST /mcp",

package/src/mcp-server.ts

@@ -1,5 +1,6 @@
 import type { Env, FileStore } from "./types"
 import type { EchoPdfConfig } from "./pdf-types"
+import { buildMcpContent, buildToolOutputEnvelope } from "./response-schema"
 import { callTool, listToolSchemas } from "./tool-registry"
 
 interface JsonRpcRequest {
@@ -19,12 +20,17 @@ const ok = (id: JsonRpcRequest["id"], result: unknown): Response =>
     { headers: { "Content-Type": "application/json" } }
   )
 
-const err = (id: JsonRpcRequest["id"], code: number, message: string): Response =>
+const err = (
+  id: JsonRpcRequest["id"],
+  code: number,
+  message: string,
+  data?: Record<string, unknown>
+): Response =>
   new Response(
     JSON.stringify({
       jsonrpc: "2.0",
       id: id ?? null,
-      error: { code, message },
+      error: data ? { code, message, data } : { code, message },
     }),
     { status: 400, headers: { "Content-Type": "application/json" } }
   )
@@ -39,6 +45,19 @@ const maybeAuthorized = (request: Request, env: Env, config: EchoPdfConfig): boo
   return request.headers.get(config.mcp.authHeader) === required
 }
 
+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,
@@ -94,7 +113,13 @@ 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",
+      status: 400,
+    })
+  }
 
   try {
     const result = await callTool(toolName, args, {
@@ -102,8 +127,32 @@ export const handleMcpRequest = async (
       env,
       fileStore,
     })
-    return ok(id, { content: [{ type: "text", text: JSON.stringify(result) }] })
+    const envelope = buildToolOutputEnvelope(result, resolvePublicBaseUrl(request, config.service.publicBaseUrl))
+    return ok(id, { content: buildMcpContent(envelope) })
   } catch (error) {
-    return err(id, -32000, error instanceof Error ? error.message : String(error))
+    const message = error instanceof Error ? error.message : String(error)
+    const status = (error as { status?: unknown })?.status
+    const stableStatus = typeof status === "number" && Number.isFinite(status) ? status : 500
+    const code = (error as { code?: unknown })?.code
+    const details = (error as { details?: unknown })?.details
+    if (message.startsWith("Unknown tool:")) {
+      return err(id, -32601, message, {
+        code: typeof code === "string" ? code : "TOOL_NOT_FOUND",
+        status: 404,
+        details,
+      })
+    }
+    if (stableStatus >= 400 && stableStatus < 500) {
+      return err(id, -32602, message, {
+        code: typeof code === "string" ? code : "INVALID_PARAMS",
+        status: stableStatus,
+        details,
+      })
+    }
+    return err(id, -32000, message, {
+      code: typeof code === "string" ? code : "INTERNAL_ERROR",
+      status: stableStatus,
+      details,
+    })
   }
 }

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({
@@ -122,9 +139,6 @@ export const runPdfAgent = async (
   const pages = ensurePages(request.pages, pageCount, config.service.maxPagesPerRequest)
   const scale = request.renderScale ?? config.service.defaultRenderScale
   const returnMode = resolveReturnMode(request.returnMode)
-  if (returnMode === "url") {
-    throw new Error("returnMode=url is not implemented; use inline or file_id")
-  }
 
   if (request.operation === "extract_pages") {
     const images: Array<{ page: number; mimeType: string; data?: string; fileId?: string; url?: string | null }> = []
@@ -138,6 +152,18 @@ export const runPdfAgent = async (
           bytes: rendered.png,
         })
         images.push({ page, mimeType: "image/png", fileId: stored.id })
+      } else if (returnMode === "url") {
+        const stored = await opts.fileStore.put({
+          filename: `${file.filename}-p${page}.png`,
+          mimeType: "image/png",
+          bytes: rendered.png,
+        })
+        images.push({
+          page,
+          mimeType: "image/png",
+          fileId: stored.id,
+          url: `/api/files/get?fileId=${encodeURIComponent(stored.id)}`,
+        })
       } else {
         images.push({
           page,
@@ -155,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") {
@@ -207,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

@@ -30,6 +30,16 @@ const validateConfig = (config: EchoPdfConfig): EchoPdfConfig => {
   if (!config.service?.name) throw new Error("service.name is required")
   if (!config.pdfium?.wasmUrl) throw new Error("pdfium.wasmUrl is required")
   if (!config.service?.storage) throw new Error("service.storage is required")
+  if (
+    typeof config.service.publicBaseUrl === "string" &&
+    config.service.publicBaseUrl.length > 0 &&
+    !/^https?:\/\//.test(config.service.publicBaseUrl)
+  ) {
+    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")
   }
@@ -65,8 +75,36 @@ 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: {
+      ...resolved.service,
+      publicBaseUrl:
+        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,
       defaultProvider:

package/src/pdf-storage.ts

@@ -1,4 +1,5 @@
 import { DurableObjectFileStore } from "./file-store-do"
+import { R2FileStore } from "./r2-file-store"
 import type { EchoPdfConfig } from "./pdf-types"
 import type { Env, FileStore, StoredFileMeta, StoredFileRecord } from "./types"
 
@@ -47,6 +48,7 @@ class InMemoryFileStore implements FileStore {
 }
 
 const fallbackStore = new InMemoryFileStore()
+const DO_SAFE_MAX_FILE_BYTES = 1_200_000
 
 export interface RuntimeFileStoreBundle {
   readonly store: FileStore
@@ -55,7 +57,20 @@ export interface RuntimeFileStoreBundle {
 }
 
 export const getRuntimeFileStore = (env: Env, config: EchoPdfConfig): RuntimeFileStoreBundle => {
+  if (env.FILE_STORE_BUCKET) {
+    const store = new R2FileStore(env.FILE_STORE_BUCKET, config.service.storage)
+    return {
+      store,
+      stats: async () => store.stats(),
+      cleanup: async () => store.cleanup(),
+    }
+  }
   if (env.FILE_STORE_DO) {
+    if (config.service.storage.maxFileBytes > DO_SAFE_MAX_FILE_BYTES) {
+      throw new Error(
+        `service.storage.maxFileBytes=${config.service.storage.maxFileBytes} exceeds DO backend limit ${DO_SAFE_MAX_FILE_BYTES}; bind FILE_STORE_BUCKET (R2) or reduce maxFileBytes`
+      )
+    }
     const store = new DurableObjectFileStore(env.FILE_STORE_DO, config.service.storage)
     return {
       store,

package/src/pdf-types.ts

@@ -22,6 +22,12 @@ export interface StoragePolicy {
 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

@@ -0,0 +1,195 @@
+import type { StoragePolicy } from "./pdf-types"
+import type { FileStore, StoredFileMeta, StoredFileRecord } from "./types"
+
+const PREFIX = "file/"
+
+type MetaFields = {
+  filename?: string
+  mimeType?: string
+  createdAt?: string
+}
+
+const toId = (key: string): string => key.startsWith(PREFIX) ? key.slice(PREFIX.length) : key
+const toKey = (id: string): string => `${PREFIX}${id}`
+
+const parseCreatedAt = (value: string | undefined, fallback: Date): string => {
+  if (typeof value === "string" && value.trim().length > 0) {
+    const ms = Date.parse(value)
+    if (Number.isFinite(ms)) return new Date(ms).toISOString()
+  }
+  return fallback.toISOString()
+}
+
+const isExpired = (createdAtIso: string, ttlHours: number): boolean => {
+  const ms = Date.parse(createdAtIso)
+  if (!Number.isFinite(ms)) return false
+  return Date.now() - ms > ttlHours * 60 * 60 * 1000
+}
+
+export class R2FileStore implements FileStore {
+  constructor(
+    private readonly bucket: R2Bucket,
+    private readonly policy: StoragePolicy
+  ) {}
+
+  async put(input: { readonly filename: string; readonly mimeType: string; readonly bytes: Uint8Array }): Promise<StoredFileMeta> {
+    const sizeBytes = input.bytes.byteLength
+    if (sizeBytes > this.policy.maxFileBytes) {
+      const err = new Error(`file too large: ${sizeBytes} bytes exceeds maxFileBytes ${this.policy.maxFileBytes}`)
+      ;(err as { status?: number; code?: string; details?: unknown }).status = 413
+      ;(err as { status?: number; code?: string; details?: unknown }).code = "FILE_TOO_LARGE"
+      ;(err as { status?: number; code?: string; details?: unknown }).details = { policy: this.policy, sizeBytes }
+      throw err
+    }
+
+    await this.cleanupInternal(sizeBytes)
+
+    const id = crypto.randomUUID()
+    const createdAt = new Date().toISOString()
+    await this.bucket.put(toKey(id), input.bytes, {
+      httpMetadata: {
+        contentType: input.mimeType,
+      },
+      customMetadata: {
+        filename: input.filename,
+        mimeType: input.mimeType,
+        createdAt,
+      },
+    })
+
+    return { id, filename: input.filename, mimeType: input.mimeType, sizeBytes, createdAt }
+  }
+
+  async get(fileId: string): Promise<StoredFileRecord | null> {
+    const obj = await this.bucket.get(toKey(fileId))
+    if (!obj) return null
+    const meta = (obj.customMetadata ?? {}) as MetaFields
+    const createdAt = parseCreatedAt(meta.createdAt, obj.uploaded)
+    const filename = meta.filename ?? fileId
+    const mimeType = meta.mimeType ?? obj.httpMetadata?.contentType ?? "application/octet-stream"
+    const bytes = new Uint8Array(await obj.arrayBuffer())
+    return {
+      id: fileId,
+      filename,
+      mimeType,
+      sizeBytes: bytes.byteLength,
+      createdAt,
+      bytes,
+    }
+  }
+
+  async list(): Promise<ReadonlyArray<StoredFileMeta>> {
+    return await this.listAllFiles()
+  }
+
+  async delete(fileId: string): Promise<boolean> {
+    await this.bucket.delete(toKey(fileId))
+    return true
+  }
+
+  async stats(): Promise<unknown> {
+    const files = await this.listAllFiles()
+    const totalBytes = files.reduce((sum, file) => sum + file.sizeBytes, 0)
+    return {
+      backend: "r2",
+      policy: this.policy,
+      stats: {
+        fileCount: files.length,
+        totalBytes,
+      },
+    }
+  }
+
+  async cleanup(): Promise<unknown> {
+    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: expired.length,
+      deletedEvicted: evict.length,
+      stats: {
+        fileCount: after.length,
+        totalBytes,
+      },
+    }
+  }
+
+  private async cleanupInternal(incomingBytes: number): Promise<void> {
+    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}`
+      )
+      ;(err as { status?: number; code?: string; details?: unknown }).status = 507
+      ;(err as { status?: number; code?: string; details?: unknown }).code = "STORAGE_QUOTA_EXCEEDED"
+      ;(err as { status?: number; code?: string; details?: unknown }).details = { policy: this.policy, totalBytes: finalTotal, incomingBytes }
+      throw err
+    }
+  }
+
+  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 []
+
+    const needFree = projected - this.policy.maxTotalBytes
+    const candidates = [...files].sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt))
+    const evict: StoredFileMeta[] = []
+    let freed = 0
+    for (const file of candidates) {
+      evict.push(file)
+      freed += file.sizeBytes
+      if (freed >= needFree) break
+      if (evict.length >= this.policy.cleanupBatchSize) break
+    }
+    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

@@ -0,0 +1,182 @@
+import type { JsonObject } from "./types"
+
+export interface ToolArtifact {
+  readonly id?: string
+  readonly kind: "image" | "pdf" | "file" | "json" | "text"
+  readonly mimeType?: string
+  readonly filename?: string
+  readonly sizeBytes?: number
+  readonly url?: string
+}
+
+export interface ToolOutputEnvelope {
+  readonly ok: true
+  readonly data: unknown
+  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)
+    : {}
+
+const inferKind = (mimeType?: string): ToolArtifact["kind"] => {
+  const mime = (mimeType || "").toLowerCase()
+  if (mime.startsWith("image/")) return "image"
+  if (mime === "application/pdf") return "pdf"
+  if (mime.includes("json")) return "json"
+  if (mime.startsWith("text/")) return "text"
+  return "file"
+}
+
+const toAbsoluteUrl = (value: string, baseUrl: string): string => {
+  try {
+    return new URL(value, baseUrl).toString()
+  } catch {
+    return value
+  }
+}
+
+const addArtifact = (artifacts: ToolArtifact[], artifact: ToolArtifact): void => {
+  if (!artifact.id && !artifact.url && !artifact.filename) return
+  artifacts.push(artifact)
+}
+
+export const buildToolOutputEnvelope = (
+  result: unknown,
+  baseUrl: string
+): ToolOutputEnvelope => {
+  const root = asObj(result)
+  const artifacts: ToolArtifact[] = []
+
+  const fileMeta = asObj(root.file)
+  if (typeof fileMeta.id === "string") {
+    addArtifact(artifacts, {
+      id: fileMeta.id,
+      kind: inferKind(typeof fileMeta.mimeType === "string" ? fileMeta.mimeType : undefined),
+      mimeType: typeof fileMeta.mimeType === "string" ? fileMeta.mimeType : undefined,
+      filename: typeof fileMeta.filename === "string" ? fileMeta.filename : undefined,
+      sizeBytes: typeof fileMeta.sizeBytes === "number" ? fileMeta.sizeBytes : undefined,
+      url: typeof root.url === "string" ? toAbsoluteUrl(root.url, baseUrl) : undefined,
+    })
+  }
+
+  const images = Array.isArray(root.images) ? root.images : []
+  for (const item of images) {
+    const image = asObj(item)
+    const fileId = typeof image.fileId === "string" ? image.fileId : undefined
+    const rawUrl = typeof image.url === "string" ? image.url : undefined
+    if (!fileId && !rawUrl) continue
+    addArtifact(artifacts, {
+      id: fileId,
+      kind: "image",
+      mimeType: typeof image.mimeType === "string" ? image.mimeType : "image/png",
+      filename: fileId ? `artifact-${fileId}.png` : undefined,
+      url: rawUrl ? toAbsoluteUrl(rawUrl, baseUrl) : undefined,
+    })
+  }
+
+  const files = Array.isArray(root.files) ? root.files : []
+  for (const item of files) {
+    const meta = asObj(item)
+    if (typeof meta.id !== "string") continue
+    addArtifact(artifacts, {
+      id: meta.id,
+      kind: inferKind(typeof meta.mimeType === "string" ? meta.mimeType : undefined),
+      mimeType: typeof meta.mimeType === "string" ? meta.mimeType : undefined,
+      filename: typeof meta.filename === "string" ? meta.filename : undefined,
+      sizeBytes: typeof meta.sizeBytes === "number" ? meta.sizeBytes : undefined,
+    })
+  }
+
+  return {
+    ok: true,
+    data: result,
+    artifacts,
+  }
+}
+
+const summarizeData = (data: unknown): string => {
+  const root = asObj(data)
+  if (typeof root.returnMode === "string" && Array.isArray(root.images)) {
+    return `Extracted ${root.images.length} page image(s) in returnMode=${root.returnMode}.`
+  }
+  if (Array.isArray(root.pages)) {
+    return `Processed ${root.pages.length} page(s).`
+  }
+  if (Array.isArray(root.files)) {
+    return `Listed ${root.files.length} file(s).`
+  }
+  if (typeof root.deleted === "boolean") {
+    return root.deleted ? "File deleted." : "File not found."
+  }
+  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) {
+    lines.push("Artifacts:")
+    for (const artifact of envelope.artifacts) {
+      const descriptor = [
+        artifact.kind,
+        artifact.filename ?? artifact.id ?? "artifact",
+        artifact.mimeType ?? "",
+        artifact.url ?? "",
+      ]
+        .filter((v) => v.length > 0)
+        .join(" | ")
+      lines.push(`- ${descriptor}`)
+    }
+  }
+  lines.push("")
+  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) {
+    if (!artifact.url) continue
+    content.push({
+      type: "resource_link",
+      name: artifact.filename ?? artifact.id ?? "artifact",
+      uri: artifact.url,
+      mimeType: artifact.mimeType ?? "application/octet-stream",
+    })
+  }
+  return content
+}

package/src/tool-registry.ts

@@ -44,7 +44,7 @@ const toolDefinitions: ReadonlyArray<ToolDefinition> = [
           filename: { type: "string" },
           pages: { type: "array", items: { type: "integer" } },
           renderScale: { type: "number" },
-          returnMode: { type: "string", enum: ["inline", "file_id"] },
+          returnMode: { type: "string", enum: ["inline", "file_id", "url"] },
         },
         required: ["pages"],
       },
@@ -168,7 +168,7 @@ const toolDefinitions: ReadonlyArray<ToolDefinition> = [
           filename: { type: "string" },
           mimeType: { type: "string" },
           base64: { type: "string" },
-          returnMode: { type: "string", enum: ["inline", "file_id"] },
+          returnMode: { type: "string", enum: ["inline", "file_id", "url"] },
         },
         required: ["op"],
       },

package/src/types.ts

@@ -11,8 +11,9 @@ export type ReturnMode = "inline" | "file_id" | "url"
 export interface Env {
   readonly ECHO_PDF_CONFIG_JSON?: string
   readonly ASSETS?: Fetcher
+  readonly FILE_STORE_BUCKET?: R2Bucket
   readonly FILE_STORE_DO?: DurableObjectNamespace
-  readonly [key: string]: string | Fetcher | DurableObjectNamespace | undefined
+  readonly [key: string]: string | Fetcher | DurableObjectNamespace | R2Bucket | undefined
 }
 
 export interface StoredFileMeta {

package/wrangler.toml

@@ -6,6 +6,10 @@ compatibility_date = "2026-03-06"
 directory = "./assets"
 binding = "ASSETS"
 
+[[r2_buckets]]
+binding = "FILE_STORE_BUCKET"
+bucket_name = "echo-pdf-files"
+
 [[durable_objects.bindings]]
 name = "FILE_STORE_DO"
 class_name = "FileStoreDO"