feat(platform): resolve agent from thread metadata and fix workflow output extraction

[larryro]

Summary

• Thread agent resolution: Store customAgentId on thread metadata when starting agent chat, then resolve the correct agent from thread metadata in triggerWorkflowCompletionResponse instead of falling back to the system default chat agent. This ensures workflow completion responses use the same agent configuration as the original conversation.
• Workflow output extraction: Fix __workflowOutput extraction to look in the nested vars.variables namespace (where persistExecutionResult stores it). When no explicit output node exists, return null instead of sanitized variables — variables are stored separately and should not leak as output.
• Completion message enhancement: Include instructions to present file download links (downloadUrl) when workflow output contains them.

Test plan

• Updated serialize_and_complete_execution_handler.test.ts — covers nested variables extraction, null fallback, storage ref resolution
• Updated on_workflow_complete.test.ts — covers null output when no persisted output exists

Summary by CodeRabbit

• New Features

  • Workflow completion messages now include instructions to present file download links found in task output to users.

• Bug Fixes

  • Improved workflow completion output handling to correctly persist and process execution results.
  • Enhanced custom agent resolution during workflow execution.

• Chores

  • Updated internal schema to track custom agents associated with chat workflows.

[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 adds customAgentId field tracking throughout the chat workflow lifecycle. The schema is updated to include customAgentId in threadMetadata, and multiple chat entry points (test, unified, webhooks) now forward this ID to the startAgentChat function, which persists it in threadMetadata. The triggerWorkflowCompletionResponse mutation now resolves the active custom agent using the stored customAgentId and dynamically updates the debugTag and hook execution accordingly. Additionally, workflow output handling is refactored to use the persisted output field instead of falling back to result.returnValue, and output extraction logic is simplified to focus solely on retrieving __workflowOutput from the nested namespace.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• feat(platform): add threadMetadata shadow table for efficient thread queries #509: Both PRs modify the threadMetadata schema and manage customAgentId field tracking in thread metadata for agent resolution purposes.
• refactor: pass full documents in event emissions #453: Both PRs adjust workflow completion output/event payloads in on_workflow_complete.ts, altering how workflow results are processed and formatted.
• refactor: use savedMessageId directly instead of re-fetching messages #803: Both PRs modify triggerWorkflowCompletionResponse in agent_tools/workflows/internal_mutations.ts, changing agent resolution and scheduler payload behavior.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 42.86% 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 title accurately summarizes the main changes: thread agent resolution from metadata and workflow output extraction fixes.

_{✏️ 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/thread-agent-resolution-and-workflow-output

---

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

Tip

CodeRabbit can suggest fixes for GitHub Check annotations.

Configure the reviews.tools.github-checks setting to adjust the time to wait for GitHub Checks to complete.

[coderabbitai]

Actionable comments posted: 2

🤖 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/workflows/internal_mutations.ts`:
- Around line 112-118: The loop currently assigns chatAgent conditionally then
unconditionally breaks, which is confusing; change the iteration to only break
when you've found the matching agent: iterate over agentQuery and inside the
loop check agent.organizationId === organizationId, set chatAgent and then break
(or continue for non-matching entries) so the loop intent is clear — update the
block around chatAgent, agentQuery and organizationId to perform the conditional
assignment and the break together.

In
`@services/platform/convex/workflow_engine/helpers/engine/serialize_and_complete_execution_handler.test.ts`:
- Around line 15-17: Replace the duplicated local helper with the shared
implementation: remove the local function isRecord and import the exported
isRecord from the shared type-guards module (the common "isRecord" export used
in production) so tests use the same type-guard as production; update any
references in serialize_and_complete_execution_handler.test.ts to use the
imported isRecord.

🪄 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: 765d4280-b32e-4674-b14d-81a25b0edf54

📥 Commits

Reviewing files that changed from the base of the PR and between 7b282f1 and 1657ab6.

📒 Files selected for processing (10)

• services/platform/convex/agent_tools/workflows/internal_mutations.ts
• services/platform/convex/custom_agents/test_chat.ts
• services/platform/convex/custom_agents/unified_chat.ts
• services/platform/convex/custom_agents/webhooks/internal_mutations.ts
• services/platform/convex/lib/agent_chat/start_agent_chat.ts
• services/platform/convex/threads/schema.ts
• services/platform/convex/workflow_engine/helpers/engine/on_workflow_complete.test.ts
• services/platform/convex/workflow_engine/helpers/engine/on_workflow_complete.ts
• services/platform/convex/workflow_engine/helpers/engine/serialize_and_complete_execution_handler.test.ts
• services/platform/convex/workflow_engine/helpers/engine/serialize_and_complete_execution_handler.ts