fill_pdf_form: fill an AcroForm PDF, and say so honestly when the PDF is a flat scan

[serge-ivo]

Part of the Gmail epic. Independent of the Gmail work — useful anywhere a form must be produced.

Why

There is no code in PAGS that writes a PDF. The only PDF handling is lib/resume-parse.ts, which sends one to Claude to read:

// lib/resume-parse.ts:65
{ type: "document", source: { type: "base64", media_type: "application/pdf", data: bytesToBase64(bytes) } },

Reading is solved; producing a filled form is not attempted anywhere.

Scope

A fill_pdf_form tool, tier: "standard", scope: "read" (it touches no external system), mutates: true (it writes a new file into the instance store).

Input: a source file id in the instance store, plus values as a field-name → value map. Output: a new file id for the filled PDF.

Two paths, because real forms are not all the same:

1. AcroForm present — fill the named fields with pdf-lib and flatten. Deterministic, and the field names can be listed back to the model first so it knows what it is filling.
2. No form fields (flat scan) — do NOT silently produce an unchanged PDF, which is the failure mode worth designing against. Report that the source has no fillable fields, and produce a clean typed answer document instead: a generated PDF listing every question and the supplied answer, suitable to attach alongside the original.

A companion read-only inspect_pdf_form that lists the field names (or reports there are none) is what makes path 1 usable — the model must not guess field names.

Risks to check during implementation

• Bundle size. pdf-lib is roughly 1 MB minified. workers/api is on the paid 10 MB limit, so this should fit, but the built size must be measured before and after rather than assumed, and it should be a dynamic import() on the handler path like lib/crypto.js and lib/gmail.js already are in storage-tools.ts.
• Worker CPU. Flattening a large scanned PDF is not free. Cap the input size and fail with a clear message rather than hitting the wall.

Not verified

Whether the forms this is actually wanted for are AcroForms. The motivating attachment has not been inspected yet, so path 2 is designed as a first-class outcome rather than an error branch. If real club forms turn out to be flat scans in the common case, path 2 is the product and path 1 is the bonus — worth re-reading this issue once a real sample exists.

[serge-ivo]

Shipped in faad6cf.

inspect_pdf_form, fill_pdf_form, build_answer_sheet. Pure logic in lib/pdf-form.ts, glue in lib/pdf-storage-tools.ts.

Both risks the issue flagged were measured, not assumed:

• Bundle: 4572 → 5529 KiB raw, 1131 → 1358 KiB gzip. Well inside the 10MB limit, dynamically imported on the handler path.
• A finding neither of us predicted: pdf-lib does not reject a value outside a dropdown's option set — it quietly adds it as a new option and reports success, so a form would go back with a selection the club's own document never offered. Caught because the test expected a throw and got a resolved promise. Now validated explicitly, case-insensitively, storing the document's own spelling.

The flat-scan path is built as the issue asked — as a first-class outcome, not an error branch. fillPdfForm refuses a formless PDF rather than returning it unchanged (pdf-lib would happily hand back a byte-identical document, and an agent attaching that has sent an empty form while reporting success), and inspect_pdf_form names build_answer_sheet in its own output.

Two things worth recording for the next reader:

• They are builtins, not registry tools. registryTools() upholds an invariant that a tool is creator-selectable IFF a connector provides it, and pipeline-tool-policy relies on it to avoid an import cycle. Registering them as connector-less registry tools broke that and would have made "declared" mean one thing in chat and another in a pipeline.
• They were briefly registered but reachable by nobody — not in any default, not creator-selectable: the same defect this repo already documents for delete_record. They now have their own documents catalog group, deliberately not in FULL.

Still unverified, as the issue said: whether the motivating attachment is an AcroForm or a flat scan. Both paths work; which one it takes is unknown until a real sample exists.