feat: accept document uploads via unified FileHandler branch

[timurvafin]

Summary

Accept a family of document uploads (PDF, Office, OpenDocument, and common text-table formats) by adding a new "document" type to FileHandler. Binary documents are persisted to <current_dir>/.uploads/<timestamp>-<name> and Claude receives a generic prompt with the absolute path — the agent picks whichever tool fits the format. Both agentic (agentic_document) and classic (handle_document) paths go through the same FileHandler method.

Design

Single document branch, one prompt

The _process_document_file method is format-agnostic. The prompt just tells Claude where the file is:

User uploaded a file:

Path: {absolute_path}

Read the file using the appropriate tool for its format and answer the user's question.

Claude infers the format from the extension and chooses Read (for PDF/text/notebooks) or Bash with an appropriate converter (pandoc, python-docx, openpyxl, unzip, etc.) for Office/OpenDocument. This means adding a new format is one line in document_extensions.

Storage

.uploads/ sits inside APPROVED_DIRECTORY, so Claude's tools reach it without tripping ToolMonitor path boundaries. The file is not deleted after the call — follow-up turns can still read or reference it without re-uploading. Timestamp prefix (YYYYMMDD-HHMMSS-fff) prevents collisions from rapid uploads.

The existing archive/code/text branches are untouched.

Formats supported

Binary (persisted, document branch):

• .pdf — Read tool (native parser)
• .docx, .xlsx, .pptx — Bash with pandoc / python-docx / openpyxl
• .odt, .ods, .odp — Bash with pandoc / LibreOffice
• .rtf — Bash with pandoc

UTF-8 text-compatible (existing text branch, inline in prompt):

• .csv, .tsv, .log, .ics, .eml

Changes

• src/security/validators.py — extend ALLOWED_EXTENSIONS with the two groups above
• src/bot/features/file_handler.py — new document_extensions set, _detect_file_type returns "document" for them, new _process_document_file persists and builds the generic prompt, handle_document_upload accepts optional current_dir (defaults to approved_directory)
• src/bot/orchestrator.py (agentic) — resolve current_dir before calling handle_document_upload, pass it through
• src/bot/handlers/message.py (classic) — same plumbing; .pdf added to supported-formats help text
• .gitignore — ignore .uploads/
• Tests — new tests/unit/test_bot/test_file_handler.py (6 tests: parametrized detection for all binary formats, CSV → text branch, unknown binary stays binary, persist + prompt shape, end-to-end PDF, fallback-to-approved-directory); validator whitelist extended + .pdf.exe regression

Known limitations

• Document conversion relies on whatever tools are available in Claude's execution environment. First attempt may pip install if pandoc/python-docx/openpyxl aren't found. Supports are graceful: Claude will report back if it can't convert a given format.
• .uploads/ has no automatic cleanup. Manual housekeeping for now — a follow-up PR could add a /new hook or cron-based LRU.
• .doc (legacy MS Word binary) and .ppt (legacy PowerPoint) intentionally excluded — they're harder to convert reliably and less common today.

Relationship to #192

This PR supersedes #192, which was a narrow patch that branched on .pdf directly in agentic_document. #192 has been closed. This PR:

• puts the logic in FileHandler where other document types already live
• gives classic mode document support as a side effect
• extends the whitelist to the full Office family
• removes the PDF-specific helper from the orchestrator
• uses a generic, format-agnostic prompt so adding more formats is trivial

Test plan

• make test — 542 passed (10 new tests)
• black/isort/flake8 clean
• Live smoke PDF: SMOKE-TOKEN-42 uploaded, saved, Claude read via Read and answered correctly
• Live smoke DOCX: SMOKE-DOCX-99 uploaded as .docx, saved to .uploads/20260424-145608-997-contract.docx, Claude converted via Bash and answered correctly
• Regression: .exe still blocked, .pdf.exe trap still blocked, files > 10 MB still rejected

🤖 Generated with Claude Code