📬 feat: Report Tool Results Per Call via onResult Channel

[danny-avila]

Summary

I wired the tool-execution handler to report each result to the agent graph as it settles, instead of only delivering the full batch at the end. The handler already runs tool batches in parallel (Promise.all over the calls), but the ON_TOOL_EXECUTE contract previously exposed only the single resolve(results[]) channel — so a 1-second tool's completion event waited for the slowest call in the same batch. The agents SDK now accepts an optional per-call onResult callback (agents#239) and emits that call's completed run step immediately when invoked; this PR is the host half.

• Pulled the optional onResult callback off the batch request with a forward-compatible cast, so this compiles against the currently installed SDK typings and activates automatically once the release containing agents#239 lands; until then onResult is undefined and the optional chain makes this a no-op.
• Wrapped both mapper exit points (direct execution and the file-authoring queue path) in a reportResult helper, so every result shape — success, error, host-tool, queued — is reported exactly once as it settles; resolve(results) remains the authoritative batch outcome and is unchanged.
• Guarded the callback invocation so a throwing listener can never break batch resolution.

The SDK side gates the fast-path on no-hooks/no-HITL configurations and dedupes against batch-time emission, so no changes are needed here for those cases — when the SDK withholds onResult, this code path is simply inert.

Change Type

• New feature (non-breaking change which adds functionality)

Testing

• Added three specs to packages/api/src/agents/handlers.spec.ts: a gated slow tool proves the fast call is reported before the batch resolves (and before the slow tool finishes); a throwing onResult listener doesn't prevent resolve; behavior without onResult is unchanged. Full handlers.spec.ts passes (78 tests).
• tsc reports no errors in the touched files.

Test Configuration:

• Node 24, jest via packages/api.

Checklist

• My code adheres to this project's style guidelines
• I have performed a self-review of my own code
• I have commented in any complex areas of my code
• My changes do not introduce new warnings
• I have written tests demonstrating that my changes are effective or that my feature works
• Local unit tests pass with my changes

[danny-avila]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Keep it up!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

GitNexus: ❌ deploy failed

The deploy failed — the previous index (if any) continues to be served.
Deploy run