feat(agent): generate file download cards in chat via appendFilePart

[Israeltheminer]

Summary

• Add appendFilePart helper and appendGeneratedFilePart internalAction to save agent-generated files as downloadable cards in the chat message (using promptMessageId from ToolCtx runtime, not the incorrectly-typed messageId)
• Call appendFilePart in all 6 file tool generate handlers (pdf, docx, pptx, excel, image, text)
• Replace downloadUrl in tool results with '[file card shown in chat]' so the model has no real URL to link in its response
• Fix text tool: z.discriminatedUnion produces type: "None" JSON schema rejected by OpenAI — converted to flat z.object with optional fields (same pattern as all other tools; added comment explaining why)
• Fix file agent instructions: line 142 said "include the download URL from the result" which directly contradicted line 119's "do NOT include the downloadUrl" — the contradiction caused the model to always output a link

Test plan

• Ask agent to generate a PDF — confirm download card appears in chat, no markdown link in response
• Ask agent to generate a DOCX, PPTX, XLSX, image, text file — same check
• Ask agent to parse an uploaded PDF — confirm parse still works normally
• Ask agent "can you give me the download link?" after generating — confirm it refers to the card button
• Verify no OpenAI schema errors for text tool in Convex logs

🤖 Generated with Claude Code

Summary by CodeRabbit

• Improvements
  • Generated files now appear as download cards directly in chat for streamlined access
  • Updated guidance: use the download button on file cards instead of manually copying links
  • Option to save generated files to documents hub folder remains available

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR integrates file parts into chat messages across multiple file generation tools. A new helper function appendFilePart is introduced to persist generated files as downloadable cards in chat by invoking internal mutations. The file tools (docx, excel, image, pdf, pptx, text) are updated to call this helper after successful generation, return a placeholder URL instead of direct download URLs, and update user guidance. New internal mutations are created to append file parts to assistant messages. The text tool's argument schema is refactored from a discriminated union to a flat object shape. Agent guidance is updated to direct users to download cards rather than direct links.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat(platform): consolidate excel tool and remove resource_check #471: Modifies excel_tool.ts with appendFilePart integration in the generate flow
• feat(crawler,platform): multi-format web extraction, DOCX generation, and image quality presets #556: Modifies docx_tool.ts argument handling and generation behavior
• feat: contract comparison workflow with chunk-level RAG #722: Updates the same suite of file-generation tools (docx, excel, pdf, pptx, image, text) for file metadata and URL handling

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title accurately describes the main change: introducing appendFilePart to generate file download cards in chat across file generation tools.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/agent-file-download-cards-backend

📝 Coding Plan

• Generate coding plan for human review comments

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Tip

Migrating from UI to YAML configuration.

Use the @coderabbitai configuration command in a PR comment to get a dump of all your UI settings in YAML format. You can then edit this YAML file and upload it to the root of your repository to configure CodeRabbit programmatically.

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@services/platform/convex/agent_tools/files/helpers/append_file_part.ts`:
- Around line 28-31: The current early return in appendFilePart (when threadId
or promptMessageId are missing) silently no-ops; change appendFilePart to return
an explicit status (e.g., Promise<boolean>) and replace the early "return" with
"return false" so callers can handle fallback deterministically; update the
function signature and all internal return paths to return true on success and
false on this precondition failure, and update callers to only mask downloadUrl
when appendFilePart(...) returns true (or handle false by throwing/using a
fallback) — refer to appendFilePart, threadId, promptMessageId, and the calling
sites that currently mask downloadUrl.

In `@services/platform/convex/agent_tools/files/internal_mutations.ts`:
- Around line 30-44: Duplicate construction of the assistant file-part payload
should be extracted into a single helper to avoid drift; create a small function
(e.g., buildAssistantFileMessage or buildFileContent) in internal_mutations.ts
that accepts filename, mimeType, and downloadUrl and returns the message.content
array/object currently inlined, then replace the duplicated inline payloads used
in the saveMessage calls (the block around saveMessage(...) at lines matching
the first occurrence and the second occurrence around 77-91) to call this helper
so both actions share the same construction logic.

In `@services/platform/convex/agent_tools/files/text_tool.ts`:
- Around line 126-132: The validation for generate currently throws before the
generate try/catch (checks on args.filename and args.content), causing uncaught
exceptions; instead, move these validations into the same try block used for
generation (or replace the throws with returning a structured TextGenerateResult
error) so missing args produce a TextGenerateResult with an error payload
consistent with the parse path; update the code paths referencing operation ===
'generate' and args to either perform the checks inside the try around the
generate logic or construct and return the TextGenerateResult error object when
validation fails.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 16d9fbe2-416d-43c5-8027-b74a8b905bb9

📥 Commits

Reviewing files that changed from the base of the PR and between b8ce578 and efcf3fd.

⛔ Files ignored due to path filters (1)

• services/platform/convex/_generated/api.d.ts is excluded by !**/_generated/**

📒 Files selected for processing (9)

• services/platform/convex/agent_tools/files/docx_tool.ts
• services/platform/convex/agent_tools/files/excel_tool.ts
• services/platform/convex/agent_tools/files/helpers/append_file_part.ts
• services/platform/convex/agent_tools/files/image_tool.ts
• services/platform/convex/agent_tools/files/internal_mutations.ts
• services/platform/convex/agent_tools/files/pdf_tool.ts
• services/platform/convex/agent_tools/files/pptx_tool.ts
• services/platform/convex/agent_tools/files/text_tool.ts
• services/platform/convex/agents/file/agent.ts