fix(packages/agents): wire up overrides.onStepFinish in flow agents

[zrosenbauer]

Summary

• FlowAgentOverrides.onStepFinish was accepted by the type system but silently dropped at runtime in flow agents — only config.onStepFinish was passed to createStepBuilder
• Added buildMergedStepFinishHook() that merges config and per-call override hooks (config fires first, then override) using the existing fireHooks/wrapHook utilities
• Applied the merged hook in both generate() and stream() paths

Test plan

• Added test: both config and override onStepFinish hooks fire during generate()
• Added test: config hook fires before override hook (sequential ordering)
• All 537 existing tests pass
• Typecheck passes

[changeset-bot]

🦋 Changeset detected

Latest commit: a412dee

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@funkai/agents	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
funkai	Ready	Preview, Comment	Mar 15, 2026 4:07am

[coderabbitai]

Warning

Rate limit exceeded

@zrosenbauer has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 2 minutes and 9 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: ac0a762a-e33e-4d4a-b071-b76ae1fb3fc9

📥 Commits

Reviewing files that changed from the base of the PR and between e124c43 and a412dee.

📒 Files selected for processing (3)

• .changeset/fix-flow-agent-override-step-hooks.md
• packages/agents/src/core/agents/flow/flow-agent.test.ts
• packages/agents/src/core/agents/flow/flow-agent.ts

📝 Walkthrough

Walkthrough

The changes introduce a merged hook mechanism in the flow agent that combines config-level and per-call override onStepFinish hooks. A new helper function constructs a merged hook that executes the config hook first, then the override hook in sequence. Tests validate that both hooks fire with correct call order and payload structure.

Changes

Cohort / File(s)	Summary
Implementation packages/agents/src/core/agents/flow/flow-agent.ts	Adds StepFinishHook private type and buildMergedStepFinishHook helper that merges optional config and override hooks, executing config first then override. Integrates merged hook into generate() and stream() methods via StepBuilder. Imports StepInfo from flow/types.js.
Tests packages/agents/src/core/agents/flow/flow-agent.test.ts	Adds test coverage for merged onStepFinish hooks in generate(), verifying both config and override hooks fire with correct call order (config before override) and payload structure (step and duration).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.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
Title check	✅ Passed	The title accurately describes the main fix: wiring up the previously ignored overrides.onStepFinish in flow agents.
Description check	✅ Passed	The description clearly explains the problem, solution, and test coverage; it directly relates to the changeset.

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

📝 Coding Plan

• Generate coding plan for human review comments

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

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

Inline comments:
In `@packages/agents/src/core/agents/flow/flow-agent.test.ts`:
- Around line 429-435: Replace the mutable shared array "order" and in-place
pushes with assertions that inspect the mocks' invocation order: make
configOnStepFinish and overrideOnStepFinish remain vi.fn() spies and after the
scenario assert that configOnStepFinish.mock.invocationCallOrder[0] <
overrideOnStepFinish.mock.invocationCallOrder[0] (or the equivalent invocation
order property available on the vi.fn mocks), removing any use of order.push and
avoiding in-place mutation.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 38473985-b83e-48f2-b5f9-c69e3dab35d1

📥 Commits

Reviewing files that changed from the base of the PR and between dbc4393 and e124c43.

📒 Files selected for processing (2)

• packages/agents/src/core/agents/flow/flow-agent.test.ts
• packages/agents/src/core/agents/flow/flow-agent.ts