feat(ai): unify onFinish callback types into shared TextOnFinishCallback #12193
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
4 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Background
PR #11888 adds output/outputError to the streamText onFinish callback. @lgrammel feedback: the three callback types (GenerateTextOnFinishCallback, StreamTextOnFinishCallback, ToolLoopAgentOnFinishCallback) share identical structure and should be unified first.
Summary
Extracted the common callback event structure into a shared TextOnFinishEvent type. All three callback types now reference this base instead of duplicating 20ish lines each.
New file: text-on-finish-callback.ts
Breaking change: ToolLoopAgentOnFinishCallback.experimental_context is now required instead of optional. This aligns it with GenerateTextOnFinishCallback and StreamTextOnFinishCallback which already had it required. Low risk because the SDK always provides this value when invoking callbacks. User code that consumes callbacks won't break since they're reading from the event, not constructing it.
Manual Verification
This is a type-only refactor with no runtime behavior changes. The callback invocation code remains identical. Verified by:
Ran existing onFinish examples to confirm callbacks still fire:
pnpm tsx src/stream-text/openai-on-finish.ts
pnpm tsx src/generate-text/openai-on-finish.ts
pnpm tsx src/agent/openai-generate-on-finish.ts
Type tests confirm all three callback types are assignable to the base TextOnFinishCallback type.
All existing tests pass for the affected modules.
No new runtime behavior to manually verify since we only changed type definitions.
Checklist
Future Work
This is PR 1 of 4 in a series to add output/outputError to all onFinish callbacks:
PR 2: Rebase #11888 - After this lands, #11888 can extend TextOnFinishEvent with an OUTPUT generic and add output/outputError properties to StreamTextOnFinishCallback.
PR 3: generateText output - Add the same OUTPUT generic and output/outputError to GenerateTextOnFinishCallback. Requires reordering generateText internals to parse output before calling onFinish.
PR 4: Agent output - Add OUTPUT generic and output/outputError to ToolLoopAgentOnFinishCallback.
Related Issues
#11888