@echofiles/echo-pdf 0.2.0

package/scripts/check-runtime.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+required_node_major="${REQUIRED_NODE_MAJOR:-20}"
+current_node_major="$(node -p "Number(process.versions.node.split('.')[0])")"
+
+if [[ -z "${current_node_major}" ]] || (( current_node_major < required_node_major )); then
+  echo "Node.js >=${required_node_major} is required. Current: $(node -v 2>/dev/null || echo 'not installed')"
+  exit 1
+fi
+
+for cmd in npm curl grep sed; do
+  if ! command -v "${cmd}" >/dev/null 2>&1; then
+    echo "Missing required command: ${cmd}"
+    exit 1
+  fi
+done
+
+if [[ "${CHECK_LLM_KEYS:-0}" == "1" ]]; then
+  if [[ -z "${OPENAI_API_KEY:-}" && -z "${OPENROUTER_KEY:-}" && -z "${OPENROUTER_API_KEY:-}" && -z "${VERCEL_AI_GATEWAY_API_KEY:-}" && -z "${VERCEL_AI_GATEWAY_KEY:-}" ]]; then
+    echo "CHECK_LLM_KEYS=1 but no provider key found (OPENAI_API_KEY / OPENROUTER_KEY / OPENROUTER_API_KEY / VERCEL_AI_GATEWAY_API_KEY / VERCEL_AI_GATEWAY_KEY)."
+    exit 1
+  fi
+fi
+
+echo "runtime check passed: node=$(node -v), npm=$(npm -v)"

package/scripts/export-fixtures.sh

@@ -0,0 +1,204 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+OUT_DIR="${ROOT_DIR}/fixtures/output"
+EXPORT_PORT="${EXPORT_PORT:-8798}"
+BASE_URL="${BASE_URL:-http://127.0.0.1:${EXPORT_PORT}}"
+INPUT_PDF="${INPUT_PDF:-${ROOT_DIR}/fixtures/input.pdf}"
+START_LOCAL_DEV="${START_LOCAL_DEV:-1}"
+RUN_TABLES="${RUN_TABLES:-1}"
+REQUIRE_LLM_SUCCESS="${REQUIRE_LLM_SUCCESS:-1}"
+
+mkdir -p "$OUT_DIR"
+rm -rf "${OUT_DIR:?}/"*
+
+if [[ -f "${ROOT_DIR}/../.env.local" ]]; then
+  set -a
+  # shellcheck source=/dev/null
+  source "${ROOT_DIR}/../.env.local"
+  set +a
+fi
+
+if [[ ! -f "${INPUT_PDF}" ]]; then
+  echo "missing input pdf: ${INPUT_PDF}" >&2
+  exit 1
+fi
+
+cli() {
+  node "${ROOT_DIR}/bin/echo-pdf.js" "$@"
+}
+
+run_json() {
+  local name="$1"
+  shift
+  if "$@" > "${OUT_DIR}/${name}.json" 2> "${OUT_DIR}/${name}.err"; then
+    rm -f "${OUT_DIR}/${name}.err"
+  else
+    printf '{"ok":false,"error_file":"%s.err"}\n' "$name" > "${OUT_DIR}/${name}.json"
+  fi
+}
+
+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"
+}
+
+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"
+}
+
+# 1) Save test logs locally (do not block artifact export on transient network failure)
+set +e
+{
+  echo "[typecheck]"
+  npm --prefix "$ROOT_DIR" run typecheck
+  TYPECHECK_CODE=$?
+  echo
+  echo "[test]"
+  npm --prefix "$ROOT_DIR" run test
+  TEST_CODE=$?
+  echo
+  echo "[smoke]"
+  npm --prefix "$ROOT_DIR" run smoke
+  SMOKE_CODE=$?
+  echo
+  echo "typecheck_exit=${TYPECHECK_CODE}"
+  echo "test_exit=${TEST_CODE}"
+  echo "smoke_exit=${SMOKE_CODE}"
+} > "${OUT_DIR}/test.log" 2>&1
+set -e
+
+cat > "${OUT_DIR}/test-status.json" <<JSON
+{"typecheck":${TYPECHECK_CODE:-1},"test":${TEST_CODE:-1},"smoke":${SMOKE_CODE:-1}}
+JSON
+
+DEV_PID=""
+cleanup() {
+  if [[ -n "${DEV_PID}" ]] && kill -0 "${DEV_PID}" >/dev/null 2>&1; then
+    kill "${DEV_PID}" >/dev/null 2>&1 || true
+    wait "${DEV_PID}" 2>/dev/null || true
+  fi
+}
+trap cleanup EXIT
+
+if [[ "${START_LOCAL_DEV}" == "1" ]]; then
+  npm --prefix "$ROOT_DIR" run dev -- --ip 127.0.0.1 --port "${EXPORT_PORT}" --inspector-port 0 > "${OUT_DIR}/export-local-dev.log" 2>&1 &
+  DEV_PID=$!
+  for _ in $(seq 1 120); do
+    if node -e 'fetch(process.argv[1]+"/health").then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))' "${BASE_URL}" >/dev/null 2>&1; then
+      break
+    fi
+    sleep 0.5
+  done
+  node -e 'fetch(process.argv[1]+"/health").then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))' "${BASE_URL}" >/dev/null
+fi
+
+# 2) Init CLI + provider settings
+cli init --service-url "$BASE_URL" > "${OUT_DIR}/cli-init.json"
+
+node -e 'const fs=require("fs");const cfg=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));const entries=Object.entries(cfg.providers||{});const pick=(key)=>{const keys=[key];if(key.endsWith("_API_KEY"))keys.push(key.replace(/_API_KEY$/,"_KEY"));if(key.endsWith("_KEY"))keys.push(key.replace(/_KEY$/,"_API_KEY"));for(const k of keys){const v=process.env[k];if(typeof v==="string"&&v.trim())return {k,v:v.trim()};}return null;};const forced=String(process.env.SMOKE_LLM_PROVIDER||"").trim();if(forced&&cfg.providers?.[forced]){const found=pick(String(cfg.providers[forced].apiKeyEnv||""));if(found){process.stdout.write(JSON.stringify({provider:forced,apiKey:found.v,env:found.k,forced:true}));process.exit(0);}}const preferred=String(cfg.agent?.defaultProvider||"");const ordered=entries.sort((a,b)=>a[0]===preferred?-1:b[0]===preferred?1:0);for(const [alias,p] of ordered){const found=pick(String(p.apiKeyEnv||""));if(found){process.stdout.write(JSON.stringify({provider:alias,apiKey:found.v,env:found.k,forced:false}));process.exit(0);}}process.stdout.write(JSON.stringify({provider:preferred||"",apiKey:"",env:"",forced:false}));' "${ROOT_DIR}/echo-pdf.config.json" > "${OUT_DIR}/provider-selection.json"
+PROVIDER="$(node -e 'const fs=require("fs");const j=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));process.stdout.write(String(j.provider||""))' "${OUT_DIR}/provider-selection.json")"
+PROVIDER_KEY="$(node -e 'const fs=require("fs");const j=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));process.stdout.write(String(j.apiKey||""))' "${OUT_DIR}/provider-selection.json")"
+PREFERRED_MODEL="${SMOKE_LLM_MODEL:-${ECHO_PDF_DEFAULT_MODEL:-}}"
+if [[ -n "${PROVIDER}" ]] && [[ -n "${PROVIDER_KEY}" ]]; then
+  cli provider set --provider "${PROVIDER}" --api-key "${PROVIDER_KEY}" > "${OUT_DIR}/provider-set.json"
+  cli provider use --provider "${PROVIDER}" > "${OUT_DIR}/provider-use.json"
+else
+  echo '{"warning":"No provider key found in env, LLM calls may fail"}' > "${OUT_DIR}/provider-warning.json"
+fi
+
+# 3) Pull models via CLI and select one
+if [[ -n "${PROVIDER}" ]]; then
+  run_json "models" cli models --provider "${PROVIDER}"
+else
+  echo '{"warning":"No provider selected, skip model list"}' > "${OUT_DIR}/models.json"
+fi
+MODEL="${PREFERRED_MODEL}"
+if [[ -n "$MODEL" ]] && [[ -n "${PROVIDER}" ]]; then
+  if ! node -e 'const fs=require("fs");const file=process.argv[1];const model=process.argv[2];const j=JSON.parse(fs.readFileSync(file,"utf8"));const models=Array.isArray(j.models)?j.models:[];process.exit(models.includes(model)?0:1)' "${OUT_DIR}/models.json" "$MODEL"; then
+    echo "Configured model not found in provider model list: ${MODEL}" >&2
+    exit 1
+  fi
+  cli model set --provider "${PROVIDER}" --model "$MODEL" > "${OUT_DIR}/model-set.json"
+else
+  echo '{"warning":"Missing ECHO_PDF_DEFAULT_MODEL / SMOKE_LLM_MODEL"}' > "${OUT_DIR}/model-warning.json"
+  exit 1
+fi
+
+# 4) Upload the exact local fixture for subsequent CLI/MCP calls
+node -e 'const fs=require("fs"); const path=require("path"); (async()=>{ const base=process.argv[1]; const file=process.argv[2]; const bytes=fs.readFileSync(file); const fd=new FormData(); fd.set("file", new Blob([bytes], {type:"application/pdf"}), path.basename(file)); const res=await fetch(`${base}/api/files/upload`, {method:"POST", body:fd}); const txt=await res.text(); fs.writeFileSync(process.argv[3], txt); if(!res.ok){process.stderr.write(txt); process.exit(1);} })().catch((e)=>{console.error(String(e)); process.exit(1)})' "$BASE_URL" "$INPUT_PDF" "${OUT_DIR}/upload.json"
+FILE_ID="$(node -e 'const fs=require("fs");const j=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));process.stdout.write(j.file?.id||"")' "${OUT_DIR}/upload.json")"
+if [[ -z "${FILE_ID}" ]]; then
+  echo "upload did not return file id" >&2
+  exit 1
+fi
+
+# 5) CLI tool calls
+run_json "tools-catalog" cli tools
+if [[ -n "${PROVIDER}" ]]; then
+  run_json "cli-extract-pages" cli call --tool pdf_extract_pages --args "{\"fileId\":\"${FILE_ID}\",\"pages\":[1],\"returnMode\":\"inline\"}" --provider "${PROVIDER}" --model "${MODEL:-}"
+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"
+
+# 6) MCP tool calls
+run_json "mcp-initialize" cli mcp initialize
+run_json "mcp-tools" cli mcp tools
+run_json "mcp-call-fileops" cli mcp call --tool file_ops --args '{"op":"list"}'
+run_json "mcp-extract-pages" cli mcp call --tool pdf_extract_pages --args "{\"fileId\":\"${FILE_ID}\",\"pages\":[1],\"returnMode\":\"inline\"}"
+
+# 7) LLM tool calls
+OCR_OK=0
+TABLES_OK=0
+if [[ -n "${PROVIDER}" ]]; then
+  : > "${OUT_DIR}/llm-attempts.log"
+  echo "[ocr] using provider=${PROVIDER} model=${MODEL}" >> "${OUT_DIR}/llm-attempts.log"
+  if cli call --tool pdf_ocr_pages --args "{\"fileId\":\"${FILE_ID}\",\"pages\":[1],\"provider\":\"${PROVIDER}\",\"model\":\"${MODEL}\"}" --provider "${PROVIDER}" --model "${MODEL}" > "${OUT_DIR}/cli-ocr-pages.json" 2> "${OUT_DIR}/cli-ocr-pages.err"; then
+    if validate_ocr_json "${OUT_DIR}/cli-ocr-pages.json"; then
+      OCR_OK=1
+      echo "{\"provider\":\"${PROVIDER}\",\"model\":\"${MODEL}\"}" > "${OUT_DIR}/ocr-selected-model.json"
+    fi
+  fi
+else
+  run_json "cli-ocr-pages" cli call --tool pdf_ocr_pages --args "{\"fileId\":\"${FILE_ID}\",\"pages\":[1]}"
+fi
+
+if [[ "${RUN_TABLES}" == "1" ]]; then
+  if [[ -n "${PROVIDER}" ]]; then
+    echo "[tables] using provider=${PROVIDER} model=${MODEL}" >> "${OUT_DIR}/llm-attempts.log"
+    if cli call --tool pdf_tables_to_latex --args "{\"fileId\":\"${FILE_ID}\",\"pages\":[1],\"provider\":\"${PROVIDER}\",\"model\":\"${MODEL}\"}" --provider "${PROVIDER}" --model "${MODEL}" > "${OUT_DIR}/cli-tables-to-latex.json" 2> "${OUT_DIR}/cli-tables-to-latex.err"; then
+      if validate_tables_json "${OUT_DIR}/cli-tables-to-latex.json"; then
+        TABLES_OK=1
+        echo "{\"provider\":\"${PROVIDER}\",\"model\":\"${MODEL}\"}" > "${OUT_DIR}/tables-selected-model.json"
+      fi
+    fi
+  else
+    run_json "cli-tables-to-latex" cli call --tool pdf_tables_to_latex --args "{\"fileId\":\"${FILE_ID}\",\"pages\":[1]}"
+  fi
+else
+  echo '{"skipped":true,"reason":"Set RUN_TABLES=1 to enable table-latex call"}' > "${OUT_DIR}/cli-tables-to-latex.json"
+fi
+
+if [[ "${REQUIRE_LLM_SUCCESS}" == "1" ]]; then
+  if [[ "${OCR_OK}" != "1" ]]; then
+    echo "OCR failed for configured model. See ${OUT_DIR}/cli-ocr-pages.err and llm-attempts.log" >&2
+    exit 1
+  fi
+  if [[ "${RUN_TABLES}" == "1" ]] && [[ "${TABLES_OK}" != "1" ]]; then
+    echo "Tables failed for configured model. See ${OUT_DIR}/cli-tables-to-latex.err and llm-attempts.log" >&2
+    exit 1
+  fi
+fi
+
+cat > "${OUT_DIR}/summary.txt" <<TXT
+base_url=${BASE_URL}
+input_pdf=${INPUT_PDF}
+file_id=${FILE_ID}
+model=${MODEL}
+outputs_dir=${OUT_DIR}
+TXT
+
+ls -la "$OUT_DIR"

package/scripts/smoke.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+bash "${SCRIPT_DIR}/check-runtime.sh"
+
+# Smoke now reuses integration tests as the single E2E source of truth.
+# Supported env vars (forwarded to integration tests):
+# - SMOKE_BASE_URL
+# - SMOKE_REQUIRE_LLM
+# - SMOKE_LLM_PROVIDER
+# - SMOKE_LLM_MODEL
+# - TESTCASE_DIR
+npm run test:integration

package/src/agent-defaults.ts

@@ -0,0 +1,25 @@
+import type { EchoPdfConfig } from "./pdf-types"
+
+const normalize = (value: string): string => value.trim()
+
+export const resolveProviderAlias = (
+  config: EchoPdfConfig,
+  requestedProvider?: string
+): string => {
+  const raw = normalize(requestedProvider ?? "")
+  if (raw.length === 0) return config.agent.defaultProvider
+  if (config.providers[raw]) return raw
+  const fromType = Object.entries(config.providers).find(([, provider]) => provider.type === raw)?.[0]
+  if (fromType) return fromType
+  throw new Error(`Provider "${raw}" not configured`)
+}
+
+export const resolveModelForProvider = (
+  config: EchoPdfConfig,
+  _providerAlias: string,
+  requestedModel?: string
+): string => {
+  const explicit = normalize(requestedModel ?? "")
+  if (explicit.length > 0) return explicit
+  return normalize(config.agent.defaultModel ?? "")
+}

package/src/file-ops.ts

@@ -0,0 +1,52 @@
+import { fromBase64, normalizeReturnMode, toInlineFilePayload } from "./file-utils"
+import type { FileStore, ReturnMode } from "./types"
+
+export const runFileOp = async (
+  fileStore: FileStore,
+  input: {
+    readonly op: "list" | "read" | "delete" | "put"
+    readonly fileId?: string
+    readonly includeBase64?: boolean
+    readonly text?: string
+    readonly filename?: string
+    readonly mimeType?: string
+    readonly base64?: string
+    readonly returnMode?: ReturnMode
+  }
+): Promise<unknown> => {
+  if (input.op === "list") {
+    return { files: await fileStore.list() }
+  }
+
+  if (input.op === "put") {
+    const bytes = input.base64 ? fromBase64(input.base64) : new TextEncoder().encode(input.text ?? "")
+    const meta = await fileStore.put({
+      filename: input.filename ?? `file-${Date.now()}.txt`,
+      mimeType: input.mimeType ?? "text/plain; charset=utf-8",
+      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 }
+    const stored = await fileStore.get(meta.id)
+    if (!stored) throw new Error(`File not found after put: ${meta.id}`)
+    return {
+      returnMode,
+      ...toInlineFilePayload(stored, true),
+    }
+  }
+
+  if (!input.fileId) {
+    throw new Error("fileId is required")
+  }
+
+  if (input.op === "delete") {
+    return { deleted: await fileStore.delete(input.fileId), fileId: input.fileId }
+  }
+
+  const file = await fileStore.get(input.fileId)
+  if (!file) throw new Error(`File not found: ${input.fileId}`)
+  return toInlineFilePayload(file, Boolean(input.includeBase64))
+}

package/src/file-store-do.ts

@@ -0,0 +1,340 @@
+import { fromBase64, toBase64 } from "./file-utils"
+import type { StoragePolicy } from "./pdf-types"
+import type { StoredFileMeta, StoredFileRecord } from "./types"
+
+interface StoredValue {
+  readonly id: string
+  readonly filename: string
+  readonly mimeType: string
+  readonly sizeBytes: number
+  readonly createdAt: string
+  readonly bytesBase64: string
+}
+
+interface StoreStats {
+  readonly fileCount: number
+  readonly totalBytes: number
+}
+
+const json = (data: unknown, status = 200): Response =>
+  new Response(JSON.stringify(data), {
+    status,
+    headers: { "Content-Type": "application/json; charset=utf-8" },
+  })
+
+const readJson = async (request: Request): Promise<Record<string, unknown>> => {
+  try {
+    const body = await request.json()
+    if (typeof body === "object" && body !== null && !Array.isArray(body)) {
+      return body as Record<string, unknown>
+    }
+    return {}
+  } catch {
+    return {}
+  }
+}
+
+const defaultPolicy = (): StoragePolicy => ({
+  maxFileBytes: 1_200_000,
+  maxTotalBytes: 52_428_800,
+  ttlHours: 24,
+  cleanupBatchSize: 50,
+})
+
+const parsePolicy = (input: unknown): StoragePolicy => {
+  const raw = typeof input === "object" && input !== null && !Array.isArray(input)
+    ? (input as Record<string, unknown>)
+    : {}
+  const fallback = defaultPolicy()
+
+  const maxFileBytes = Number(raw.maxFileBytes ?? fallback.maxFileBytes)
+  const maxTotalBytes = Number(raw.maxTotalBytes ?? fallback.maxTotalBytes)
+  const ttlHours = Number(raw.ttlHours ?? fallback.ttlHours)
+  const cleanupBatchSize = Number(raw.cleanupBatchSize ?? fallback.cleanupBatchSize)
+
+  return {
+    maxFileBytes: Number.isFinite(maxFileBytes) && maxFileBytes > 0 ? Math.floor(maxFileBytes) : fallback.maxFileBytes,
+    maxTotalBytes: Number.isFinite(maxTotalBytes) && maxTotalBytes > 0 ? Math.floor(maxTotalBytes) : fallback.maxTotalBytes,
+    ttlHours: Number.isFinite(ttlHours) && ttlHours > 0 ? ttlHours : fallback.ttlHours,
+    cleanupBatchSize:
+      Number.isFinite(cleanupBatchSize) && cleanupBatchSize > 0 ? Math.floor(cleanupBatchSize) : fallback.cleanupBatchSize,
+  }
+}
+
+const toMeta = (value: StoredValue): StoredFileMeta => ({
+  id: value.id,
+  filename: value.filename,
+  mimeType: value.mimeType,
+  sizeBytes: value.sizeBytes,
+  createdAt: value.createdAt,
+})
+
+const listStoredValues = async (state: DurableObjectState): Promise<StoredValue[]> => {
+  const listed = await state.storage.list<StoredValue>({ prefix: "file:" })
+  return [...listed.values()]
+}
+
+const computeStats = (files: ReadonlyArray<StoredValue>): StoreStats => ({
+  fileCount: files.length,
+  totalBytes: files.reduce((sum, file) => sum + file.sizeBytes, 0),
+})
+
+const isExpired = (createdAt: string, ttlHours: number): boolean => {
+  const createdMs = Date.parse(createdAt)
+  if (!Number.isFinite(createdMs)) return false
+  return Date.now() - createdMs > ttlHours * 60 * 60 * 1000
+}
+
+const deleteFiles = async (state: DurableObjectState, files: ReadonlyArray<StoredValue>): Promise<number> => {
+  let deleted = 0
+  for (const file of files) {
+    const ok = await state.storage.delete(`file:${file.id}`)
+    if (ok) deleted += 1
+  }
+  return deleted
+}
+
+export class FileStoreDO {
+  constructor(private readonly state: DurableObjectState) {}
+
+  async fetch(request: Request): Promise<Response> {
+    const url = new URL(request.url)
+
+    if (request.method === "POST" && url.pathname === "/put") {
+      const body = await readJson(request)
+      const policy = parsePolicy(body.policy)
+      const filename = typeof body.filename === "string" ? body.filename : `file-${Date.now()}`
+      const mimeType = typeof body.mimeType === "string" ? body.mimeType : "application/octet-stream"
+      const bytesBase64 = typeof body.bytesBase64 === "string" ? body.bytesBase64 : ""
+
+      const bytes = fromBase64(bytesBase64)
+      if (bytes.byteLength > policy.maxFileBytes) {
+        return json(
+          {
+            error: `file too large: ${bytes.byteLength} bytes exceeds maxFileBytes ${policy.maxFileBytes}`,
+            code: "FILE_TOO_LARGE",
+            policy,
+          },
+          413
+        )
+      }
+
+      let files = await listStoredValues(this.state)
+      const expired = files.filter((file) => isExpired(file.createdAt, policy.ttlHours))
+      if (expired.length > 0) {
+        await deleteFiles(this.state, expired)
+        files = await listStoredValues(this.state)
+      }
+
+      let stats = computeStats(files)
+      const projected = stats.totalBytes + bytes.byteLength
+      if (projected > policy.maxTotalBytes) {
+        const needFree = projected - policy.maxTotalBytes
+        const candidates = [...files]
+          .sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt))
+          .slice(0, policy.cleanupBatchSize)
+
+        let freed = 0
+        const evictList: StoredValue[] = []
+        for (const file of candidates) {
+          evictList.push(file)
+          freed += file.sizeBytes
+          if (freed >= needFree) break
+        }
+        if (evictList.length > 0) {
+          await deleteFiles(this.state, evictList)
+          files = await listStoredValues(this.state)
+          stats = computeStats(files)
+        }
+      }
+
+      if (stats.totalBytes + bytes.byteLength > policy.maxTotalBytes) {
+        return json(
+          {
+            error: `storage quota exceeded: total ${stats.totalBytes} + incoming ${bytes.byteLength} > maxTotalBytes ${policy.maxTotalBytes}`,
+            code: "STORAGE_QUOTA_EXCEEDED",
+            policy,
+            stats,
+          },
+          507
+        )
+      }
+
+      const id = crypto.randomUUID()
+      const value: StoredValue = {
+        id,
+        filename,
+        mimeType,
+        sizeBytes: bytes.byteLength,
+        createdAt: new Date().toISOString(),
+        bytesBase64,
+      }
+      await this.state.storage.put(`file:${id}`, value)
+      return json({ file: toMeta(value), policy })
+    }
+
+    if (request.method === "GET" && url.pathname === "/get") {
+      const fileId = url.searchParams.get("fileId")
+      if (!fileId) return json({ error: "Missing fileId" }, 400)
+      const value = await this.state.storage.get<StoredValue>(`file:${fileId}`)
+      if (!value) return json({ file: null })
+      return json({ file: value })
+    }
+
+    if (request.method === "GET" && url.pathname === "/list") {
+      const listed = await this.state.storage.list<StoredValue>({ prefix: "file:" })
+      const files = [...listed.values()].map(toMeta)
+      return json({ files })
+    }
+
+    if (request.method === "POST" && url.pathname === "/delete") {
+      const body = await readJson(request)
+      const fileId = typeof body.fileId === "string" ? body.fileId : ""
+      if (!fileId) return json({ error: "Missing fileId" }, 400)
+      const key = `file:${fileId}`
+      const existing = await this.state.storage.get(key)
+      if (!existing) return json({ deleted: false })
+      await this.state.storage.delete(key)
+      return json({ deleted: true })
+    }
+
+    if (request.method === "GET" && url.pathname === "/stats") {
+      let policyInput: unknown
+      const encoded = url.searchParams.get("policy")
+      if (encoded) {
+        try {
+          policyInput = JSON.parse(encoded)
+        } catch {
+          policyInput = undefined
+        }
+      }
+      const policy = parsePolicy(policyInput)
+      const files = await listStoredValues(this.state)
+      const stats = computeStats(files)
+      return json({ policy, stats })
+    }
+
+    if (request.method === "POST" && url.pathname === "/cleanup") {
+      const body = await readJson(request)
+      const policy = parsePolicy(body.policy)
+      const files = await listStoredValues(this.state)
+      const expired = files.filter((file) => isExpired(file.createdAt, policy.ttlHours))
+      const deletedExpired = await deleteFiles(this.state, expired)
+
+      const afterExpired = await listStoredValues(this.state)
+      let stats = computeStats(afterExpired)
+      let deletedEvicted = 0
+      if (stats.totalBytes > policy.maxTotalBytes) {
+        const sorted = [...afterExpired].sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt))
+        const evictList: StoredValue[] = []
+        for (const file of sorted) {
+          evictList.push(file)
+          const projected = stats.totalBytes - evictList.reduce((sum, item) => sum + item.sizeBytes, 0)
+          if (projected <= policy.maxTotalBytes) break
+          if (evictList.length >= policy.cleanupBatchSize) break
+        }
+        deletedEvicted = await deleteFiles(this.state, evictList)
+        stats = computeStats(await listStoredValues(this.state))
+      }
+
+      return json({
+        policy,
+        deletedExpired,
+        deletedEvicted,
+        stats,
+      })
+    }
+
+    return json({ error: "Not found" }, 404)
+  }
+}
+
+export class DurableObjectFileStore {
+  constructor(
+    private readonly namespace: DurableObjectNamespace,
+    private readonly policy: StoragePolicy
+  ) {}
+
+  private stub(): DurableObjectStub {
+    return this.namespace.get(this.namespace.idFromName("echo-pdf-file-store"))
+  }
+
+  async put(input: {
+    readonly filename: string
+    readonly mimeType: string
+    readonly bytes: Uint8Array
+  }): Promise<StoredFileMeta> {
+    const response = await this.stub().fetch("https://do/put", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        filename: input.filename,
+        mimeType: input.mimeType,
+        bytesBase64: toBase64(input.bytes),
+        policy: this.policy,
+      }),
+    })
+    const payload = (await response.json()) as { file?: StoredFileMeta; error?: string }
+    if (!response.ok || !payload.file) {
+      throw new Error(payload.error ?? "DO put failed")
+    }
+    return payload.file
+  }
+
+  async get(fileId: string): Promise<StoredFileRecord | null> {
+    const response = await this.stub().fetch(`https://do/get?fileId=${encodeURIComponent(fileId)}`)
+    const payload = (await response.json()) as { file?: StoredValue | null }
+    if (!response.ok) throw new Error("DO get failed")
+    if (!payload.file) return null
+    return {
+      id: payload.file.id,
+      filename: payload.file.filename,
+      mimeType: payload.file.mimeType,
+      sizeBytes: payload.file.sizeBytes,
+      createdAt: payload.file.createdAt,
+      bytes: fromBase64(payload.file.bytesBase64),
+    }
+  }
+
+  async list(): Promise<ReadonlyArray<StoredFileMeta>> {
+    const response = await this.stub().fetch("https://do/list")
+    const payload = (await response.json()) as { files?: StoredFileMeta[] }
+    if (!response.ok) throw new Error("DO list failed")
+    return payload.files ?? []
+  }
+
+  async delete(fileId: string): Promise<boolean> {
+    const response = await this.stub().fetch("https://do/delete", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ fileId }),
+    })
+    const payload = (await response.json()) as { deleted?: boolean }
+    if (!response.ok) throw new Error("DO delete failed")
+    return payload.deleted === true
+  }
+
+  async stats(): Promise<{ policy: StoragePolicy; stats: StoreStats }> {
+    const policyEncoded = encodeURIComponent(JSON.stringify(this.policy))
+    const response = await this.stub().fetch(`https://do/stats?policy=${policyEncoded}`)
+    const payload = (await response.json()) as { policy: StoragePolicy; stats: StoreStats }
+    if (!response.ok) throw new Error("DO stats failed")
+    return payload
+  }
+
+  async cleanup(): Promise<{ policy: StoragePolicy; deletedExpired: number; deletedEvicted: number; stats: StoreStats }> {
+    const response = await this.stub().fetch("https://do/cleanup", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ policy: this.policy }),
+    })
+    const payload = (await response.json()) as {
+      policy: StoragePolicy
+      deletedExpired: number
+      deletedEvicted: number
+      stats: StoreStats
+    }
+    if (!response.ok) throw new Error("DO cleanup failed")
+    return payload
+  }
+}