Epic: the emailed-form workflow stops at step 2 — download is broken (#755), Word is unreadable (#763), and only the byte-upload parameter is genuinely missing (#762)

[proagentstore]

Rewritten 2026-08-28. Two premises in the original were wrong and would have sent an implementer to build things that already exist. Corrections are marked CORRECTION below. The workflow the owner asked for is unchanged and is tracked by the checklist.

The workflow

A form arrives by email. The agent should:

1. Find and read the message
2. Put the attachment in the instance file store as a real file
3. Read the form well enough to complete it
4. Save the completed output as a new file
5. Reply in the original thread with that file attached — ideally after a human has looked at it

Concrete case that motivated this:

• Gmail message 1a00cff038273010, instance e17d538d-6940-4773-80f6-3715c1b2d2fa
• Junior Comp Hawthorn Entry Form SUMMER 2026:2027.doc (application/msword)
• Hawthorn Club Championships 2026.docx
• Reply target: the original Kelly / Hawthorn Tennis thread

This is a high-frequency shape, not an edge case: club entries, school forms, permission slips, supplier forms, onboarding packs, insurance forms. The agent currently reads the email, understands the instructions, names the attachments — and stops exactly where the delegated work begins.

Priority — P2: correctness: three of the five steps are already shipped. What is left is one live defect (#755) and one missing parameter (#762), not a new product area. The one genuinely open question is #764.

---

Where each step actually stands — VERIFIED

Step	Status	Where
1. Read the message	Shipped	gmail_search, gmail_read_message — lib/connectors/gmail.ts:524-549 (#711)
2. Attachment → file store	Built, broken	gmail_download_attachment refuses the id it was given — #755
3. Read/fill the form	PDF only	inspect_pdf_form / fill_pdf_form / build_answer_sheet — lib/pdf-storage-tools.ts:66-92 (#712). No Word path — #763, #764
4. Save the result as a file	Reachable everywhere except from a tool	DO route takes contentBase64; upload_file does not — #762
5. Reply in-thread with the file	Shipped	gmail_reply attachment_file_ids — lib/connectors/gmail.ts:561 (#713). Draft-before-send is missing — #765

CORRECTION 1 — there IS a binary path; no tool exposes it

The original said "there is no obvious way for an external connector/tool to place an edited binary Word document back into the instance file store." That is wrong at the layer that matters, and building it from scratch would duplicate live code.

• workers/api/src/agent-do-storage-routes.ts:150-154 — if (!body.name || (!body.content && !body.contentBase64)) … then const data = body.contentBase64 ? bytesFromBase64(body.contentBase64).slice().buffer : body.content;
• workers/api/src/routes/storage.ts:167-175 forwards the request body verbatim, so contentBase64 already reaches the DO over HTTP today
• workers/api/src/lib/connectors/gmail.ts:226 — the Gmail downloader uses it in production right now: contentBase64: base64UrlToBase64(base64url),

What is true is narrower: upload_file is text-only — workers/api/src/lib/storage-tools.ts:86, content: { type: "string", description: "File content (text)", required: true } — and so is MCP upload_agent_file (workers/mcp/src/storage-tools.ts:271). That is one parameter, tracked as #762, not an epic.

CORRECTION 2 — step 5 already ships

The original said "the missing binary download/edit/upload path means there may be no usable file ID to attach." The attach path itself is complete and tested: gmail_reply takes attachment_file_ids (connectors/gmail.ts:561), collectOutgoingAttachments (:327-347) resolves each id to real bytes with a 15MB total cap, and gmail.test.ts:409 covers it. Recipients come from the parent message and can never be model-supplied (connectors/gmail.ts:349-356).

What is genuinely missing at step 5 is the draft: both tools state "This really sends: there is no draft step and no undo" (connectors/gmail.ts:556, :570). Tracked as #765 — and it needs no new OAuth scope, because gmail.modify is already requested and recorded.

CORRECTION 3 — .doc and .docx are not one problem, and the user's file is the hard one

The original treated ".doc / .docx forms" as a single gap. They are different problems with different answers:

	.docx	.doc
Container	ZIP of XML	OLE2 / CFB compound binary
Readable in a Worker	yes — the runtime already uses DecompressionStream twice (agent-storage-utils.ts:200, repo-ingest.ts:205) and already hand-rolls an archive walker (repo-ingest.ts:245, readTar)	realistically no

extractFileText handles text and PDF and nothing else — workers/api/src/agent-storage-utils.ts:141-149, catch-all return { text: "", status: "unsupported" };. So both formats land in the store contributing nothing, and read_file refuses them honestly (storage-tools.ts:365-369).

The user's actual attachment is the .doc. A complete .docx implementation would not have finished the reported task. Split as #763 (read a .docx) and #764 (the decision about how far Word fill goes, and whether .doc is in scope at all).

CORRECTION 4 — the "flat form" fallback already exists

build_answer_sheet (pdf-storage-tools.ts:85-92) already generates "a clean PDF of questions and their answers… send it alongside the original rather than attaching an empty form." It was built for flat-scan PDFs, but it is the same answer for a Word form with no structured fields — which is what a club form usually is. This may make the expensive option (true .docx fill) unnecessary; that is the open question in #764.

---

The children

• gmail_download_attachment refuses the id gmail_read_message just handed the model — the validation re-fetch is what fails, and the download endpoint never needed the round-trip #755 — gmail_download_attachment refuses the id gmail_read_message handed the model. Blocks step 2; nothing else can start. P1
• upload_file is text-only, so no tool can put bytes in the file store — the DO route, the API route and one live caller already take contentBase64 #762 — upload_file cannot write bytes; add a base64 parameter. Step 4. P2
• A stored .docx contributes nothing — extractFileText handles text and PDF only, so read_file and RAG see an empty document (and .doc is a different, harder problem) #763 — a stored .docx contributes nothing; extractFileText has no Word path. Step 3, read half. P2
• [decision] How far does Word form handling go — .docx is tractable, .doc is not, and build_answer_sheet may already be the right answer for both #764 — [decision] how far Word form handling goes; .docx vs .doc, and whether build_answer_sheet is already the answer. Step 3, fill half — the only research problem here. P3
• An agent cannot draft an email for a human to read — gmail_reply and gmail_send always go straight to the wire, and the gmail.modify scope a draft needs is already granted #765 — no draft step before an external reply. Step 5, the review affordance. P2

#755 → #762 → #763 is a complete, shippable chain that ends with the agent able to read an emailed .docx and reply with a generated answer sheet. #764 gates nothing except the "fill the original document in place" version of step 3; it must not gate the other four.

---

The question that needs the owner, not a developer

Is "the agent replies with a clean answer-sheet PDF alongside the original form" an acceptable outcome, or must the returned file be the original document with the values in it?

Answer it on #764. Everything downstream of it — whether .docx write support is built, whether .doc needs an external converter and whether that is acceptable for the owner's documents — follows from it, and it cannot be read out of the code.

Related history: #710 is the closed epic that built steps 1, 3 (PDF) and 5. It left one thing explicitly unverified — "Whether real-world club forms like the motivating one are AcroForms or flat scans… Not reproduced — needs the actual attachment." This issue is the answer, and it is worse than either branch #710 anticipated: they were not PDFs at all.

[proagentstore]

Business context

This is not just a generic document-conversion feature request. It is a common high-value personal assistant workflow:

A user receives a real-world form by email, asks the agent to complete it, and expects the agent to handle the whole loop: find the email, download the attachment, fill the form from known/user-provided details, and reply with the completed document attached.

Concrete example from the user session:

• The user needed to respond to a Hawthorn Tennis Club junior summer competition email from Kelly.
• The email contained a Word .doc entry form and a .docx club championship form.
• The user’s goal was simple: fill the competition form and send it back before the team-registration deadline.
• The PAGS agent could read and summarize the email, but could not complete the job because the attachment could not be moved reliably into agent Files and there is no Word form-fill path.

Why this matters for PAGS

This is exactly the type of delegated task users expect an agent platform to own. The user should not need to manually download a file, upload it into a separate tool, convert formats, re-upload it, and then ask the agent to send a reply. That manual handoff breaks the value proposition of a connected agent.

The business value is broad:

• Parents and clubs: school forms, sports registrations, permission slips, competition entries.
• Job seekers: emailed application forms, onboarding forms, references, candidate packs.
• Small businesses: supplier forms, insurance forms, account-opening documents, event registrations.
• Admin work: receive a form, complete it, return it, with the agent retaining context and attachments.

Product expectation

A Gmail-connected PAGS agent with Files and reply tools should support this end-to-end path:

1. Search/read the relevant email.
2. Save one or more attachments into agent Files as binary files.
3. Inspect/fill common form formats: .doc, .docx, and PDF.
4. Save the completed output as a new file.
5. Create a draft reply or send a reply with the completed file attached, depending on permissions and user confirmation.

For safety, the preferred UX is draft/review by default for external replies with attachments, with explicit send when the user asks.

Current user-visible failure

The user experiences the platform as almost capable but unable to finish: it can find the message, understand the instructions, see the attachments, and has a Gmail reply tool, but cannot bridge the attachment into Files and cannot fill the Word form. That makes the workflow stall at the exact point where the agent should be most useful.