Propagate invocation context through agents

[goatrenterguy]

The problem

I was integrating PostHog LLM observability on top of agent middleware and ran
into a wall with sub-agents. When an agent is used as a tool, AgentTool::handle()
calls $this->agent->prompt(...) and the sub-agent gets a brand new invocationId
with nothing tying it back to the agent that called it. So in Posthog the parent
and sub-agent show up as two separate traces instead of one tree, with no way to
reconstruct "this agent delegated to that one."

The solution

I added a InvocationContext that carries the current invocation's id plus its parent and root, and keeps it active for the duration of a prompt() or stream(). A sub-agent's prompt() runs on the same call stack, so it inherits them automatically. The ids are exposed as parentInvocationId and rootInvocationId on AgentPrompt and AgentResponse for middleware or a listener to read. Streaming re-establishes the context inside the lazy generator, and the queue path serializes the ids onto the InvokeAgent job so a queued agent dispatched inside an invocation still nests under it.

I built this for PostHog, but I checked the tracing models for a few other tools (OpenTelemetry, Langfuse, LangSmith, Helicone) and they all group by a root/trace id and nest children under a parent, so the same parent/root invocation ids map onto them too. Helicone is the one slight outlier, it nests by a session path rather than a parent id, but the lineage still feeds it.

Heads up

I mostly work in React but we have a Laravel backend, so some of my PHP might less than ideal. Happy to
adjust anything. I did use Claude to help me through some of this, but I have gone through and reviewed it.

[pushpak1300]

I'm going to mark this as a draft for now rather than merge. The reason is sequencing: #652 is mid-flight, and it relocates the recursive tool loop out of the individual gateways into a centralized TextGenerationLoop. That tool loop is the exact seam this PR hooks into for sub-agent nesting, so landing invocation context now means threading it through an architecture we're actively tearing down — and then reworking it again once the loop lands.

I'd rather solve this once, properly, on top of the refactor than do it twice. TextGenerationLoop is the natural single home for invocation lineage — one insertion point that every provider flows through, instead of threading context through GeneratesText, StreamsText, and each gateway.

So: keeping this open as a draft for reference. Once #652 settles, we can retarget against 0.x and rebuild lineage on the loop. No changes needed here in the meantime.

[goatrenterguy]

I'm going to mark this as a draft for now rather than merge. The reason is sequencing: #652 is mid-flight, and it relocates the recursive tool loop out of the individual gateways into a centralized TextGenerationLoop. That tool loop is the exact seam this PR hooks into for sub-agent nesting, so landing invocation context now means threading it through an architecture we're actively tearing down — and then reworking it again once the loop lands.

I'd rather solve this once, properly, on top of the refactor than do it twice. TextGenerationLoop is the natural single home for invocation lineage — one insertion point that every provider flows through, instead of threading context through GeneratesText, StreamsText, and each gateway.

So: keeping this open as a draft for reference. Once #652 settles, we can retarget against 0.x and rebuild lineage on the loop. No changes needed here in the meantime.

That makes sense. Probably worth discussing if middleware or events are a better for telemetry. Events might be a bit simpler and allow for latency tracking