feat: middleware V2

[xavidop]

Description

Re-design middleware to implement a v2 to wrap, generate, models and tools

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code refactoring
• Performance improvement
• Test improvements
• CI/CD improvements

Testing

• Unit tests added/updated
• Integration tests added/updated
• Manual testing performed
• All existing tests pass

Checklist

• My code follows the project's code style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Documentation

• README updated
• Plugin documentation updated
• API documentation updated
• Sample code updated

[gemini-code-assist]

Code Review

This pull request introduces the V2 GenerationMiddleware system, which provides granular hooks for the generation pipeline (Generate, Model, and Tool). It includes the core interfaces, parameter objects, and a base implementation, along with comprehensive tests and a new sample project. The Genkit class has been updated to support these hooks during generation, and a new ReflectionServerV2 has been implemented using WebSockets and JSON-RPC 2.0 for improved dev tool integration. Review feedback identified a critical bug in the action cancellation logic where all actions were interrupted regardless of trace ID, a missing implementation for streaming in the reflection server, and a failure to collect tools provided by middleware.

[xavidop]

@pavelgj can you re-review?

[pavelgj]

just want to call one critical usecase to test for:

when restarting an interrupted tool, the middleware should trigger. But not just trigger, it must follow the same lifecycle. Ex, typically what happens inside a generate call:

generate - 1
    model
    tool1
    tool2
    tool3
    generate - 2
        model
        tool4
        generate - 3
            model
            // done

each of these lines can have a hook inside the generate middleware. Let's say we literally add a log statement that produces the above output.

Now, if one of those tools restartable and it interrupts. Let's say tool4... so the output would look something like:

generate - 1
    model
    tool1
    tool2
    tool3
    generate - 2
        model
        tool4 // <--- INTERUPT

so, when we restart the tool, it would continue execution as in the top output... right from the point where it got interrupted.

        generate - 1 // this is extra, but this is the restart generate call, generate call starts with generate
            tool4 // RESTART
            generate - 2
                model
                // done

i'm calling this out, because I had to fix this in JS. The implementation was naive and it looked something like:

        generate - 1
            tool4 // RESTART
            model
            // done

which is wrong.

[xavidop]

oooh, good point, let me review that

[xavidop]

this should be fixed, added a sample that covers this:

===========================================================
  Middleware Interrupt Restart Lifecycle Test
===========================================================

>>> Step 1: Initial generate (expecting tool4 to interrupt)
-----------------------------------------------------------
generate - 1
    model
21:44:58.778 [com.google.genkit.samples.MiddlewareInterruptRestartSample.main()] DEBUG c.google.genkit.core.tracing.Tracer - OpenTelemetry tracer initialized with telemetry exporter
21:45:08.941 [com.google.genkit.samples.MiddlewareInterruptRestartSample.main()] DEBUG c.g.g.core.telemetry.TelemetryConfig - Using GlobalOpenTelemetry for meter: genkit
    tool1
    tool2
    tool3
    tool4

>>> tool4 interrupted as expected!

>>> Step 2: Restart tool4 (expecting nested lifecycle)
-----------------------------------------------------------
generate - 1
    tool4
    generate - 2
        model

>>> Restart completed. Final response:
All tasks have been executed:

- Task 1 result: **tool1-result**
- Task 2 result: **tool2-result**
- Task 3 result: **tool3-result**
- Task 4 confirmation result: **tool4-confirmed-result**

===========================================================
  Full Lifecycle Log
===========================================================
generate - 1
    model
    tool1
    tool2
    tool3
    tool4
generate - 1
    tool4
    generate - 2
        model

===========================================================
  Verification
===========================================================
Restart fires wrapTool for tool4: true
Restart has nested generate:      true
Nested generate calls model:      true