@echofiles/echo-pdf 0.2.0 → 0.3.0

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）
 
 安装：
@@ -117,7 +124,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 +182,7 @@ curl -sS -X POST https://echo-pdf.echofilesai.workers.dev/tools/call \
 
 - `agent.defaultProvider`
 - `agent.defaultModel`
+- `service.publicBaseUrl`
 - `service.maxPdfBytes`
 - `service.storage.maxFileBytes`
 - `service.storage.maxTotalBytes`
@@ -184,7 +193,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 +204,7 @@ 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_MCP_KEY`（可选，启用 MCP 鉴权）
 - `ECHO_PDF_WORKER_NAME`（CLI 默认 URL 推导）
 
@@ -235,6 +247,19 @@ INPUT_PDF=./fixtures/input.pdf ./scripts/export-fixtures.sh
 
 当前实现要求模型输出中必须包含合法 `\\begin{tabular}...\\end{tabular}`。如果模型返回解释性文本或超时，会直接报错。
 
-### 8.3 `returnMode=url` 为什么不可用
+### 8.3 `returnMode=url` 如何使用
+
+`url` 模式会把结果落到存储层，并返回一个可直接 `GET` 的下载地址：
 
-当前版本没有对外文件下载路由或签名 URL 能力，因此 `url` 模式未实现。请使用 `inline` 或 `file_id`。
+- `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"}
+  }'
+```

package/echo-pdf.config.json

@@ -1,6 +1,7 @@
 {
   "service": {
     "name": "echo-pdf",
+    "publicBaseUrl": "https://echo-pdf.echofilesai.workers.dev",
     "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.0",
   "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/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,9 @@ 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 sseResponse = (stream: ReadableStream<Uint8Array>): Response =>
   new Response(stream, {
     headers: {
@@ -117,7 +140,7 @@ 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,
@@ -163,9 +186,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 +221,7 @@ export default {
         })
         return json(result)
       } catch (error) {
-        return json({ error: toError(error) }, 500)
+        return jsonError(error, 500)
       }
     }
 
@@ -253,7 +276,7 @@ export default {
         })
         return json(result)
       } catch (error) {
-        return json({ error: toError(error) }, 500)
+        return jsonError(error, 500)
       }
     }
 
@@ -276,8 +299,23 @@ 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 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)
+      headers.set("Cache-Control", "no-store")
+      if (download) {
+        headers.set("Content-Disposition", `attachment; filename=\"${file.filename.replace(/\"/g, "")}\"`)
       }
+      return new Response(file.bytes, { status: 200, headers })
     }
 
     if (request.method === "GET" && url.pathname === "/api/files/stats") {
@@ -321,6 +359,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,9 @@ 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
+
 export const handleMcpRequest = async (
   request: Request,
   env: Env,
@@ -95,6 +104,12 @@ export const handleMcpRequest = async (
 
   const toolName = typeof params.name === "string" ? params.name : ""
   const args = 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 +117,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

@@ -122,9 +122,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 +135,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,

package/src/pdf-config.ts

@@ -30,6 +30,13 @@ 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 (!Number.isFinite(config.service.storage.maxFileBytes) || config.service.storage.maxFileBytes <= 0) {
     throw new Error("service.storage.maxFileBytes must be positive")
   }
@@ -65,8 +72,16 @@ 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 withOverrides: EchoPdfConfig = {
     ...resolved,
+    service: {
+      ...resolved.service,
+      publicBaseUrl:
+        typeof publicBaseUrlOverride === "string" && publicBaseUrlOverride.trim().length > 0
+          ? publicBaseUrlOverride.trim()
+          : resolved.service.publicBaseUrl,
+    },
     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,7 @@ export interface StoragePolicy {
 export interface EchoPdfConfig {
   readonly service: {
     readonly name: string
+    readonly publicBaseUrl?: string
     readonly maxPdfBytes: number
     readonly maxPagesPerRequest: number
     readonly defaultRenderScale: number

package/src/r2-file-store.ts

@@ -0,0 +1,180 @@
+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>> {
+    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,
+      }
+    })
+  }
+
+  async delete(fileId: string): Promise<boolean> {
+    await this.bucket.delete(toKey(fileId))
+    return true
+  }
+
+  async stats(): Promise<unknown> {
+    const files = await this.list()
+    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 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 totalBytes = after.reduce((sum, file) => sum + file.sizeBytes, 0)
+    return {
+      backend: "r2",
+      policy: this.policy,
+      deletedExpired,
+      deletedEvicted,
+      stats: {
+        fileCount: after.length,
+        totalBytes,
+      },
+    }
+  }
+
+  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)
+    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 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> {
+    const totalBytes = files.reduce((sum, f) => sum + f.sizeBytes, 0)
+    const projected = totalBytes + incomingBytes
+    if (projected <= this.policy.maxTotalBytes) return 0
+
+    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
+    }
+    if (evict.length === 0) return 0
+    await this.bucket.delete(evict.map((f) => toKey(f.id)))
+    return evict.length
+  }
+}
+

package/src/response-schema.ts

@@ -0,0 +1,146 @@
+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 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."
+}
+
+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(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"