feat: add hook middleware support

[minorcell]

Summary

• add middleware-capable hook handling for turn start, action, observation, and final stages
• document new optional hook payloads and middleware usage and adjust UI hook signatures
• add runtime test covering middleware ordering and optional hooks

Testing

• bun test (fails: dependency installation blocked by 403 errors from registry mirror)

---

Codex Task

✨ PR Description

Purpose: Add extensible hook middleware system to agent session lifecycle, enabling chainable callbacks for turn events, tool actions, observations, and final outputs with support for logging and tracing integrations.

Main changes:

• Implemented middleware chain execution with runHookChain function supporting both simple callbacks and next-based middleware
• Added four lifecycle hooks: onTurnStart, onAction, onObservation, onFinal with typed payload objects replacing callback parameters
• Replaced direct onObservation callback with hook middleware pattern throughout agent turn execution loop
• Created comprehensive test suite validating middleware execution order and payload propagation across hook chain

Generated by LinearB AI and added by gitStream.
_{AI-generated content may contain inaccuracies. Please verify before using.
💡 Tip: You can customize your AI Description using Guidelines Learn how}

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[linearb]

✨ PR Review

The PR introduces a well-structured hook middleware system with comprehensive testing. The implementation follows a clean middleware pattern with proper error handling for duplicate next() calls.

2 issues detected:

🐞 Bug - Using fn.length for function signature detection is unreliable with modern JavaScript function patterns.

Details: The middleware detection logic uses fn.length to distinguish between regular callbacks and middleware functions. This approach can fail for functions with optional parameters, default values, or rest parameters, as fn.length only counts required parameters. This could lead to incorrect middleware classification and unexpected behavior.
File: packages/core/src/runtime/session.ts

🧹 Maintainability - Type assertion reduces type safety and maintainability.

Details: The type assertion bypasses TypeScript's type checking when calling the function. This reduces type safety and could hide potential runtime errors if the function signature doesn't match the expected callback interface.
File: packages/core/src/runtime/session.ts

Generated by LinearB AI and added by gitStream.
_{AI-generated content may contain inaccuracies. Please verify before using.
💡 Tip: You can customize your AI Review using Guidelines Learn how}