feat: add middleware dependency resolution

[casey-quinn]

Summary

• add middleware dependency resolver with ordering, dedupe, and cycle detection
• extend AgentMiddleware metadata and wire resolution into create_agent
• document middleware specs and cover new behaviours with unit tests

Testing

• make test
• make lint
• uv tool run pre-commit -- run --all-files

Fixes #33885
Refs agyn-sandbox#1

[casey-quinn]

Tests:

• make test (563 passed, 9 skipped)
• make test_fast (555 passed, 9 skipped)

Lint:

• make lint
• uv tool run pre-commit -- run --all-files

[noa-lucent]

Thanks for the thorough dependency resolver work — the overall design and test coverage look solid. I did notice one compatibility regression: by assigning a default id to every middleware and registering the user-provided list with merge_strategy="error", any agent that currently passes two instances of the same middleware class will now raise a duplicate-id error with no way to opt out. That was previously supported, so we need to keep the original behaviour (e.g. auto-generate unique ids when no explicit id is set, or only enforce duplicate checks once the user has opted into a specific id). Once that’s addressed I’m happy to take another look.

[noa-lucent]

[major] Registering the top-level middleware with merge_strategy="error" means we now raise on two differently-configured instances of the same middleware class, because _get_middleware_id gives every instance the class name as its default id. Today create_agent(middleware=[FooMiddleware(...), FooMiddleware(...)]) works and executes both instances; after this change it fails with "Duplicate middleware id …" even though the user never opted into dedupe, and the top-level list doesn’t offer any way to specify a different merge strategy. Could we keep the old behaviour (e.g. auto-generate unique ids when no id was provided, or only enforce the duplicate check when the user explicitly opted into an id) so existing agents that reuse a middleware twice don’t break?

[casey-quinn]

Update: addressed regression where anonymous middleware instances collided on generated IDs.

• auto-generate deterministic unique IDs for middleware without explicit identifiers while keeping the first instance's class name
• added regression test and docs note covering multiple instances of the same middleware class
• re-ran make test (564 passed, 9 skipped), make lint, uv tool run pre-commit -- run --all-files

[noa-lucent]

The auto-ID generator resolves the earlier duplicate-id regression—user-supplied middleware without explicit identifiers now keep working while explicit ids still follow the merge strategy. I also spot-checked the dependency resolver against the new tests and docs: ordering, constraints, and deduplication remain deterministic, and the documentation accurately reflects the behaviour. Looks great!

[mdrxy]

What are we doing making a new docs directory? The docs are here https://github.com/langchain-ai/docs

[casey-quinn]

@mdrxy Thanks for the note — we’ve moved middleware.md to the separate docs repo per project conventions and removed in-repo docs from this PR. Docs PR: langchain-ai/docs#1455