Handbook

Task `playwright_extract_file` v1

Deterministic, read-only extraction of text and metadata from PPTX, XLSX, DOCX, and PDF bytes. Bytes may come from a policy-permitted download_readonly on an attached playwright session or from local fixture bytes in…

Updated

Task playwright_extract_file v1

Summary

Deterministic, read-only extraction of text and metadata from PPTX, XLSX, DOCX, and PDF bytes. Bytes may come from a policy-permitted download_readonly on an attached playwright session or from local fixture bytes in offline tests. Produces a FileExtractionResult wire object with a nested UnifiedItem (source_system file). No upload, mutation, or credential export.

Read-only policy

Allowed: read-only download refs from the session facade; local byte buffers in tests; parse and normalize into UnifiedItem + extracted_text.

Disallowed: write-back to cloud storage; sharing/permission changes; exporting cookies, tokens, or storage state; calling Graph/SharePoint REST for file content outside the attached browser session.

Inputs

Field Type Required Notes
session_ref string no Required when file_ref is a session download ref; omit for pure local bytes in tests.
file_ref string no* Session download ref or stable read-only locator.
local_bytes_b64 string no* Base64 file bytes for offline/fake runs only.
filename string yes Hint for format routing (.pptx, .xlsx, .docx, .pdf).
mime_type string no Optional MIME hint when extension is ambiguous.

* Exactly one of file_ref or local_bytes_b64 must be provided.

Output

Field Type Required Notes
schema_version string yes Must be "1".
item object yes UnifiedItem with source_system file.
mime_type string no Detected or supplied MIME.
byte_length integer no Size of parsed bytes.
extracted_text string no Plain text when extraction succeeds.
warnings array no Non-fatal parse warnings (strings).

Examples

Offline DOCX fixture:

{
  "local_bytes_b64": "UEsDBAoAAAAA…",
  "filename": "note.docx"
}

{
  "schema_version": "1",
  "item": {
    "schema_version": "1",
    "item_id": "file:note.docx",
    "source_system": "file",
    "item_type": "document",
    "source_kind": "docx",
    "title": "note.docx"
  },
  "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
  "byte_length": 2048,
  "extracted_text": "Hello",
  "warnings": []
}

Failure modes

Kind When
not_attached file_ref requires session but session_ref is missing or invalid.
policy_denied Download or format blocked by read-only policy.
download_error Read-only download failed.
parse_failed Unsupported or corrupt file bytes.
invalid_query Neither file_ref nor local_bytes_b64 provided.

SchemaFailure when output JSON does not match contract.json output_schema.

Verification

  • Validate output against contract.json output_schema.
  • item.source_system must be file.
  • Wire output passes secret redaction (sanitize_for_wire).

Skipped-live behavior

  • Default tests pass local_bytes_b64 from fixtures; no live session or network.
  • Live session download tests use marker playwright_live and remain skipped unless explicitly enabled.

Changelog

  • v1 — Initial read-only file extraction contract.