feat(guardrails): add HITL escalation for decorator-style guardrails [AL-289]

[apetraru-uipath]

Stacked on #888 (feat/langchain_guardrails_escalations). Review/merge that first; this PR's base should be retargeted to main once #888 merges.

What changed?

Brings the HITL escalation capability added for middleware guardrails in #888 to the decorator path (@guardrail(action=EscalateAction(...))).

• _langchain_adapter.py — adds a _run_action() helper that publishes the guardrail runtime context (scope / stage / component) on a ContextVar around each action call (tool/LLM/agent, PRE+POST), mirroring the middleware's _base.py. This lets EscalateAction derive Component / ExecutionStage at runtime instead of requiring them hardcoded. EscalateAction and _action_context are reused unchanged from feat: add EscalateAction HITL middleware action for guardrails [AL-289] #888.
• No exception-handling change: the action call sites already catch only GuardrailBlockException, so a LangGraph GraphInterrupt raised by the escalation propagates naturally and the run suspends.
• samples/joke-agent-decorator — adds an AGENT-scope EMAIL-PII EscalateAction on create_joke_agent (env-configurable app name/folder, same app as the middleware sample), plus README scenarios. Bumps the sample's uipath-langchain constraint to >=0.11.13, <0.12.0 to match the current SDK and the middleware sample.
• Out of scope (follow-up): node / plain-function @guardrail escalation — those go through the core @guardrail in uipath-python, which doesn't publish context.

How has this been tested?

• Unit: tests/guardrails/test_adapter_context_publishing.py — asserts the adapter publishes GuardrailActionContext (scope/stage/component) for tool/LLM/agent, resets it afterward, skips the action on PASS, and re-raises GraphInterrupt.
• Integration: TestDecoratorEscalation in tests/cli/test_guardrails_in_langgraph.py — real adapter + EscalateAction + LangGraph interrupt/Command resume with MemorySaver: suspend payload (Component=Agent, ExecutionStage=PreExecution, JSON ToolInputs), approve substitutes the reviewed input, reject raises AgentRuntimeError. Payload matches the middleware flavor.
• ruff check, ruff format --check, mypy all clean.
• Live against Guardrail.Escalation.Action.App.2 (alpha / APetraruTenant): suspend creates the Action Center task with Component=Agent / ExecutionStage=PreExecution; approve resumes and completes; reject terminates with AgentRuntimeError: PII detected: Email.

Are there any breaking changes?

None.

[Copilot]

Pull request overview

Adds HITL escalation parity for decorator-style guardrails by publishing guardrail runtime context (scope/stage/component) around action invocations in the LangChain/LangGraph @guardrail adapter, enabling EscalateAction to derive Component and ExecutionStage at runtime (matching the middleware behavior introduced in #888).

Changes:

• Add _run_action() helper in the decorator adapter to publish/reset GuardrailActionContext via ContextVar around each action call and to convert GuardrailBlockException into AgentRuntimeError while letting GraphInterrupt bubble up.
• Add unit and integration coverage validating context publishing, reset semantics, PASS behavior (no action), and interrupt propagation/resume for decorator escalation.
• Update the joke-agent-decorator sample to demonstrate AGENT-scope EMAIL PII escalation and bump its uipath-langchain dependency constraint to the current SDK range.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/uipath_langchain/guardrails/_langchain_adapter.py	Publishes guardrail action context around decorator-path action calls via _run_action() for TOOL/LLM/AGENT scopes.
tests/guardrails/test_adapter_context_publishing.py	New unit tests asserting context publication/reset and GraphInterrupt propagation for decorator adapter call sites.
tests/cli/test_guardrails_in_langgraph.py	Adds decorator-path escalation E2E tests verifying interrupt → resume behavior and payload parity with middleware.
samples/joke-agent-decorator/graph.py	Demonstrates agent-scope EscalateAction configured via env vars for the escalation action app.
samples/joke-agent-decorator/README.md	Documents the new decorator-path escalation scenario and how to run/resume.
samples/joke-agent-decorator/pyproject.toml	Updates the sample’s uipath-langchain version constraint to >=0.11.13,<0.12.0.