[CoronRing]

Summary

Finishes #1675 on top of #1695. Stacked on #1695: merge that first. Until then this diff also shows its commits; the change here is only the last commit, fix(middleware): announce shared middleware once per session ....

#1695 stops deep-copying model middleware, so one instance is now shared across every run. That exposed two things:

• Guardrail traces lose their name from the second run on. Middleware emitted its middleware.creation event once per instance (a _has_registered flag). Session documents resolve middleware names from that session's creation events only (observability/node_internals.py), so a shared guard's rail_name came out as "" in every run after the first. Node-level middleware already had this problem on main; fix: shallow-copy flow context and model_middleware instead of deepcopy #1695 extends it to model_middleware, where guardrails live.
• rt.couple still deep-copied the existing middleware (Node.extend_middleware / extend_model_middleware). A coupled agent got its own MaxCalls budget and its own Lock, and middleware holding a threading.Lock or DB connection raised TypeError.

Changes:

• Creation events once per session. The registry of announced middleware now lives on SessionContext and is passed by reference to every frame derived from it (with_scope_pushed, restore_scope), so it lives exactly as long as the session. claim_middleware_registration in context/central.py returns False outside a session, where emit has nowhere to publish, so a call outside a run no longer uses up the first run's announcement.
• rt.couple shares instances. extend_middleware / extend_model_middleware build a new list but keep the instances.
• Removed ConversationMemory.__deepcopy__. It only existed to work around the copy in extend_middleware.
• Docs: couple docstring and the MaxCalls sharing note.

Fixes #1675

Type of change

• Bug fix
• Feature
• Breaking change
• Docs
• Refactor / chore / build / tests

Checklist

• Lint & format pass (ruff check . && ruff format .)
• Tests added/updated and pass locally (pytest tests)
• Docs updated if user-facing behavior changed
• Breaking changes include migration notes

Notes

Tests. All 17 new tests fail with this commit's source changes reverted and pass with them:

Area	Tests
Session registry	new contexts start empty; pushed scopes and restore_scope share it; once per session; new session resets; nothing claimed outside a session
Creation events, end to end	shared node and model middleware announce once in every run, however often they run; concurrent runs each get one; original + coupled node share one per run; an announcement outside a session doesn't use up the first run
Guardrail trace	rail_name is set in both of two runs of the same flow (integration)
rt.couple	keeps node and model middleware instances (agents and function_node); middleware holding a threading.Lock or sqlite3.Connection; coupled agent spends the original MaxCalls budget
ConversationMemory	a coupled agent still fills the caller's memory handle

Full unit + integration suite: 4076 passed. The only failures were the 2 MCP integration tests, which pip install an MCP server and couldn't in my local env. mkdocs build --strict passes.

Behaviour change. A coupled node now shares its middleware with the node it came from, as agent_node / function_node already do (see the comment in node_builder.py). For MaxCalls and Lock that's the point. For a custom stateful middleware it means state is shared across the original and coupled node rather than starting fresh.

Not changed. Node.safe_copy still deep-copies node attributes. I checked it with a non-copyable object passed as a node argument and the run, to_vertices() and graph_serialization() all work, since node instances don't keep their call arguments. So I left it out of scope.

[Pooria90]

Thanks @CoronRing.
The PR looks clean to me and nothing is blocking. I have two comments:

1. Please edit the comments that refer to the old process-wide middleware. My Claude flagged these:

• utils/logging/run_view.py:62
• cli/viz_api/queries/_common.py:208-212
• cli/viz_api/queries/middleware.py:139-146
• cli/viz_api/queries/guardrails.py:46-49

2. The fact that middleware are shared now, make the concurrent sessions fail esp if the user does not properly handle stateful middleware. We need to document this behavior, refer them to proper implementations like MaxCalls and likely provide some tools for them so they can make stateful middleware more easily.