refactor(packages/agents): extract shared generate/stream setup

[zrosenbauer]

Summary

• Extract prepareGeneration() in agent.ts to deduplicate ~170 lines of identical setup between generate() and stream() (model resolution, tool building, prompt building, output resolution, hook firing, step counter)
• Extract prepareFlowAgent() in flow-agent.ts to deduplicate input validation, logger resolution, context creation, step builder creation, user message push, and onStart hook firing
• No behavior change — pure refactor

Test plan

• pnpm test --filter=@funkai/agents passes (all existing tests)
• pnpm typecheck passes
• pnpm build --filter=@funkai/agents succeeds

[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 3:37am

[changeset-bot]

🦋 Changeset detected

Latest commit: 27f60ca

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

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 20f5617c-818f-4777-9dcc-47cf4b24bef2

📥 Commits

Reviewing files that changed from the base of the PR and between 6f83342 and 27f60ca.

📒 Files selected for processing (3)

• .changeset/refactor-extract-prepare-helpers.md
• packages/agents/src/core/agents/base/agent.ts
• packages/agents/src/core/agents/flow/flow-agent.ts

---

📝 Walkthrough

Walkthrough

Extracted shared preparation logic into dedicated helpers for base and flow agents (prepareGeneration and prepareFlowAgent), consolidating validation, model/tool/system/prompt/output resolution, context/logger setup, and hook invocation; generate() and stream() now call these preparers and use their returned prepared context.

Changes

Cohort / File(s)	Summary
Base Agent Preparation Layer packages/agents/src/core/agents/base/agent.ts	Added PreparedGeneration and prepareGeneration() to centralize input validation, model/tool/system/prompt/output resolution, hook invocation (onStart/onStepFinish/onError), and result shaping. Replaced duplicated setup in generate() and stream() with calls to prepareGeneration(). Added internal helpers (readOverride, safeSerializedLength, valueOrUndefined, resolveOptionalOutput, extractProperty, extractUsage, pickByOutput).
Flow Agent Preparation Layer packages/agents/src/core/agents/flow/flow-agent.ts	Added PreparedFlowAgent and prepareFlowAgent(input, overrides, writer) to centralize validation, logger/context resolution, step builder creation (with writer), initial user message push, and onStart hook firing. Refactored generate() and stream() to use prepareFlowAgent() and removed duplicated initialization logic.
Metadata / Release .changeset/refactor-extract-prepare-helpers.md	New changeset documenting the refactor and intended package bump.

Sequence Diagram(s)

sequenceDiagram
  participant Caller as Caller
  participant AgentPrep as prepareGeneration / prepareFlowAgent
  participant AgentExec as Agent (generate / stream)
  participant Model as LanguageModel/Tools
  participant Hooks as Hooks (onStart,onStepFinish,onError)

  Caller->>AgentPrep: invoke generate/stream with input & overrides
  AgentPrep-->>AgentPrep: validate input, resolve logger, context, prompts, outputs
  AgentPrep->>Hooks: fire onStart with prepared context
  AgentPrep->>AgentExec: return prepared context
  Caller->>AgentExec: proceed with execution (uses prepared context)
  AgentExec->>Model: call model/tools with resolved prompts/context
  Model-->>AgentExec: respond with generation/results
  AgentExec->>Hooks: onStepFinish (toolCalls/toolResults/usage transformed)
  alt error
    AgentExec->>Hooks: onError (uses validated.input)
    AgentExec-->>Caller: throw/error propagate
  else success
    AgentExec-->>Caller: return final result/stream
  end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• fix(packages/agents): prevent unhandled promise rejections in stream() #11 — Modifies the same generate()/stream() implementations in agent.ts and flow-agent.ts (related refactor/stream handling changes).

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 60.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 change: extracting shared setup logic from generate/stream methods to reduce duplication.
Description check	✅ Passed	The description is directly related to the changeset, detailing the extraction of prepareGeneration() and prepareFlowAgent() helper functions and confirming no behavior changes.

_{✏️ 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]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/agents/src/core/agents/flow/flow-agent.ts (1)

1-1: ⚠️ Potential issue | 🟡 Minor

Pipeline failure: OXFMT formatting check.

CI reports OXFMT formatting check failed for this file. Run oxfmt --write to fix.

🤖 Prompt for AI Agents

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

In `@packages/agents/src/core/agents/flow/flow-agent.ts` at line 1, The file fails
OXFMT formatting; run the formatter and commit the changes: execute `oxfmt
--write` (or your project's formatting script) on the file containing the import
of AsyncIterableStream in packages/agents/src/core/agents/flow/flow-agent.ts,
then stage and commit the updated formatted file so the OXFMT CI check passes.

🤖 Prompt for all review comments with AI agents

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

Outside diff comments:
In `@packages/agents/src/core/agents/flow/flow-agent.ts`:
- Line 1: The file fails OXFMT formatting; run the formatter and commit the
changes: execute `oxfmt --write` (or your project's formatting script) on the
file containing the import of AsyncIterableStream in
packages/agents/src/core/agents/flow/flow-agent.ts, then stage and commit the
updated formatted file so the OXFMT CI check passes.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 7e63887a-6a8d-418c-ada5-1886e368390d

📥 Commits

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

📒 Files selected for processing (2)

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