Skip to content

Commit 5d89397

Browse files
committed
chore(sessions): keep Redis identity guard current with main
Merge current upstream main while preserving the watched Redis state transaction and canonical key checks. Remove an identical test introduced by overlapping upstream changes. Refs google#7464
2 parents b4dcdf5 + 61efa30 commit 5d89397

1,036 files changed

Lines changed: 148776 additions & 25695 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/adk-architecture/references/architecture-node-runner.md‎

Lines changed: 24 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -78,12 +78,28 @@ Orchestrator
7878
configured delay, increments `attempt_count` and rebuilds the child Context
7979
from scratch. Retry count is **not** persisted, so it does not survive a
8080
resume.
81+
- A child started with `ctx.run_node()` that fails reaches the node as
82+
`DynamicNodeFailError`. The child's runner already emitted the error event,
83+
so NodeRunner only matches the retry policy against the child's error. A
84+
node with a `retry_config` copies the run-id counters under it at the start
85+
of every attempt (`_snapshot_dynamic_children`), and a retry for such a
86+
failure restores that copy (`_reset_dynamic_children_for_retry`). The retry
87+
then hands out the same run ids and replays the children the failed attempt
88+
completed, at any depth. A retry for the node's own exception keeps the
89+
counters, so its children run again.
90+
- A parallel worker (`_ParallelWorker`, or a `Node` with
91+
`parallel_worker=True`) is not retried for an item's `DynamicNodeFailError`
92+
(`_delegates_item_retry`): the item node already applied the retry policy
93+
to that item.
94+
- A `Workflow` reports a failing child by setting `ctx.error` rather than
95+
raising, and NodeRunner applies the retry policy to that error as well.
8196
- When retries are exhausted, the error is recorded on `ctx.error` and
8297
`ctx.error_node_path` and the Context is returned normally — NodeRunner does
8398
not re-raise to the orchestrator.
84-
- `NodeInterruptedError` from a dynamic child is swallowed here: the child's
85-
interrupt IDs are already on `ctx`, so the caller just reads
86-
`ctx.interrupt_ids`.
99+
- `NodeInterruptedError` from a dynamic child is swallowed here, and the
100+
interrupt IDs it carries are merged into `ctx`. `ctx.run_node()` writes them
101+
only onto the context it was called on, which is a separate `ToolContext`
102+
when the child runs from a tool, so `ctx` may not have them yet.
87103
- When `abort_signal` is triggered (`ic.is_aborted` is `True`), active node
88104
tasks are cancelled without retrying. In `_node_runner_utils`, the outer
89105
workflow runner loop catches the cancellation, calls
@@ -96,4 +112,8 @@ Orchestrator
96112
When a child is scheduled with `use_as_output=True`, its output Event also
97113
counts as the parent's output. NodeRunner sets `ctx._output_delegated`, drops
98114
the output field from the parent's own event (keeping the event if it still
99-
carries deltas), and stamps `node_info.output_for` with the ancestor paths.
115+
carries content, an error code or message, deltas or a route, and keeping the
116+
output beside an error code so rehydration does not read the node as failed),
117+
stamps `node_info.output_for` with the ancestor paths, and publishes non-tool
118+
output events on the outermost explicit claiming ancestor's branch (leaving
119+
tool responses such as `finish_task` paired on the child's branch).

‎.agents/skills/adk-architecture/references/interface-workflow.md‎

Lines changed: 79 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -9,35 +9,37 @@ graph nodes and tracks dynamic nodes spawned by `ctx.run_node()`.
99
Workflow manages two kinds of child nodes through a unified scheduler (`DynamicNodeScheduler`):
1010

1111
- **Static (graph) nodes** — declared in `edges`, compiled into a
12-
`Graph`. Scanned upfront into `_LoopState.recovered_executions` by
13-
`ReplayManager.scan_workflow_events(ctx)`. When scheduled by the
14-
orchestration loop, `_start_node_task` checks `check_interception` on any
15-
recovered execution to mark `_LoopState.replayed_nodes` and pre-populate
16-
`_LoopState.runs[node_path]` (`DynamicNodeRun` with `is_static=True`), then
17-
delegates to `ctx._run_node_internal` (`DynamicNodeScheduler`). Tracked in
18-
`_LoopState.nodes` by node name (`NodeState`).
12+
`Graph`. Scanned upfront by `ReplayManager.scan_workflow_events(ctx)` and
13+
seeded into `_LoopState.runs[node_path]` (`DynamicNodeRun`). When scheduled
14+
by the orchestration loop, `_start_node_task` marks the entry with
15+
`is_static=True`, points `_LoopState.static_runs[node_name]` at that same
16+
`DynamicNodeRun`, checks `_classify_static_replay` to populate
17+
`_LoopState.replayed_nodes`, and delegates to `ctx._run_node_internal`
18+
(`DynamicNodeScheduler`).
1919
- **Dynamic nodes** — spawned at runtime via `ctx.run_node()` from
2020
inside a graph node's `_run_impl`. Lazily rehydrated from `ReplayManager`
2121
by `DynamicNodeScheduler._rehydrate_from_events` and tracked in
2222
`_LoopState.runs` by full `node_path` (`DynamicNodeRun`,
23-
which holds `state: NodeState`, `output`, `task`, `transfer_to_agent`,
24-
`recovered_state`, and `is_static`). Managed by `DynamicNodeScheduler`.
23+
which holds `state: NodeState`, `output`, `route`, `branch`, `task`,
24+
`transfer_to_agent`, `recovered_state`, and `is_static`). Managed by
25+
`DynamicNodeScheduler`.
2526

26-
Static and dynamic nodes share the same `DynamicNodeScheduler`, replay
27-
interception (`check_interception` / `ReplayManager`), and
28-
`_LoopState.interrupt_ids` set, so the Workflow sees a unified view of
29-
execution and all pending interrupts.
27+
Static and dynamic nodes share the same `DynamicNodeScheduler`, `DynamicNodeRun`
28+
outcome recording (`record_outcome`), replay interception
29+
(`check_interception` / `ReplayManager`), and `_LoopState.interrupt_ids` set,
30+
so the Workflow sees a single unified view of execution and all pending
31+
interrupts.
3032

3133
## Implementing a graph node
3234

3335
A graph node is a regular BaseNode placed in a Workflow's edges.
34-
In `_start_node_task`, the Workflow checks `check_interception` against
35-
`_LoopState.recovered_executions` (to record `_LoopState.replayed_nodes` and
36-
seed `_LoopState.runs` with `is_static=True`) and dispatches
36+
In `_start_node_task`, the Workflow classifies any pre-seeded `DynamicNodeRun`
37+
in `_LoopState.runs` (to record `_LoopState.replayed_nodes`), indexes it under
38+
`_LoopState.static_runs[node_name]`, and dispatches
3739
`ctx._run_node_internal` to `DynamicNodeScheduler`, which either returns a
3840
replayed mock `Context` (`create_mock_context`) or wraps the node in a
39-
`NodeRunner` with a child `Context`, reading `ctx.output`, `ctx.route`, and
40-
`ctx.interrupt_ids` after it completes.
41+
`NodeRunner` with a child `Context`; `_handle_completion` then records the
42+
final outcome on the shared `DynamicNodeRun` in deterministic loop order.
4143

4244
**Output** — two paths. At most one per execution. The Workflow
4345
reads the output to pass downstream.
@@ -158,13 +160,17 @@ Within a single step (`_execute_step`), when replay is enabled:
158160
concurrent `run.task`, or calls `check_interception(node=curr_node,
159161
recovered=run.recovered_state, current_run=run)`:
160162

161-
1. **Same-turn dedup / waiting (`current_run` present and `not current_run.is_static`)** —
163+
1. **Same-turn dedup / failed / waiting (`current_run` present and `not current_run.is_static`)** —
162164
if `current_run.state.status == COMPLETED`, returns `should_run=False` with
163-
`current_run.output` and `current_run.transfer_to_agent`. If `WAITING` with
164-
`interrupts`, returns `should_run=False` with those `interrupts`. (Every
165-
static dispatch gets a fresh `run_id`, so loop edges never reuse a
166-
`node_path`; static runs have `is_static=True` so no-outcome static nodes
167-
fast-forward in step 7 via `should_run = (current_run is not None and not current_run.is_static)`.)
165+
`current_run.output`, `current_run.route`, and
166+
`current_run.transfer_to_agent`. If `FAILED`, returns `should_run=True`
167+
with `resume_inputs=recovered.resolved_responses` so a dynamic run that
168+
failed in the current turn reruns instead of consulting stale recovered
169+
events. If `WAITING` with `interrupts`, returns `should_run=False` with
170+
those `interrupts`. (Every static dispatch gets a fresh `run_id`, so loop
171+
edges never reuse a `node_path`; static runs have `is_static=True` so
172+
no-outcome static nodes fast-forward in step 7 via
173+
`should_run = (current_run is not None and not current_run.is_static)`.)
168174

169175
2. **Nested `Workflow` (`isinstance(node, Workflow)`)** — before checking
170176
completion or interrupts, `check_interception` immediately returns
@@ -175,7 +181,12 @@ Within a single step (`_execute_step`), when replay is enabled:
175181

176182
3. **Waiting / Partial resume (`recovered.interrupt_ids - recovered.resolved_ids` non-empty)** —
177183
- If `node.rerun_on_resume` is `True` and `recovered.resolved_ids` is
178-
non-empty (**partial resume**): returns `should_run=True` with
184+
non-empty (**partial resume**): if `recovered.finished_after_resume` is
185+
`True` and the node either recorded a result (`recovered.output`,
186+
`recovered.route`, or `recovered.transfer_to_agent`) or has
187+
`not node.wait_for_output`, fast-forwards (`should_run=False`) with the
188+
rehydrated `output`, `route`, and `transfer_to_agent` (and no
189+
`interrupts`); otherwise returns `should_run=True` with
179190
`resume_inputs=recovered.resolved_responses`.
180191
- Otherwise: returns `should_run=False` with `interrupts=unresolved`,
181192
propagating unresolved interrupt IDs to `_state.interrupt_ids` via a
@@ -201,9 +212,14 @@ Within a single step (`_execute_step`), when replay is enabled:
201212
`resume_inputs=recovered.resolved_responses`.
202213

203214
7. **No output, route, or interrupts in recovered events** —
204-
- If `node.wait_for_output` or `node.rerun_on_resume`: returns
215+
- If `node.wait_for_output` and the node is a `BaseAgent` (task or chat
216+
mode), or `node.rerun_on_resume` with `wait_for_output`: returns
205217
`should_run=True` with `resume_inputs=recovered.resolved_responses`.
206-
- Otherwise: returns `should_run = (current_run is not None and not current_run.is_static)`
218+
- Else if `node.rerun_on_resume`: fast-forwards (`should_run=False`) when
219+
`recovered.finished_after_resume`, otherwise returns `should_run=True`
220+
with `resume_inputs`.
221+
- Otherwise (including any other `wait_for_output` node, whose next trigger
222+
starts a new run): returns `should_run = (current_run is not None and not current_run.is_static)`
207223
(static nodes that completed with `None` output fast-forward with
208224
`should_run=False`, while dynamic nodes with no recorded outcome
209225
re-execute with `should_run=True`).
@@ -212,7 +228,8 @@ Within a single step (`_execute_step`), when replay is enabled:
212228

213229
When a dynamic child interrupts:
214230

215-
1. `DynamicNodeScheduler._record_result` sets the child's `DynamicNodeRun`
231+
1. **Dynamic child interrupts**:
232+
`DynamicNodeRun.record_outcome` sets the child's `DynamicNodeRun`
216233
status to WAITING and adds its interrupt IDs to
217234
`_LoopState.interrupt_ids`.
218235
2. `ctx.run_node()` checks `child_ctx.interrupt_ids`. If non-empty,
@@ -349,24 +366,30 @@ Key behaviors:
349366
On every run, `Workflow` reconstructs progress from session events in three
350367
stages:
351368

352-
1. **Upfront static scan (`ReplayManager.scan_workflow_events`)** — during
369+
1. **Upfront child scan (`ReplayManager.scan_workflow_events`)** — during
353370
`_run_impl` SETUP, `ReplayManager` scans the invocation's events and
354-
populates `loop_state.recovered_executions` (keyed by `node_name@run_id`)
355-
with outputs, routes, interrupts, resolved function responses, error codes,
356-
and transfers for direct static children. `Workflow` then seeds `START`
371+
`Workflow` seeds `_LoopState.runs[node_path]` with `DynamicNodeRun` entries
372+
carrying outputs, routes, interrupts, resolved function responses, error
373+
codes, and transfers for direct children. `Workflow` then seeds `START`
357374
triggers normally (`_seed_start_triggers`).
358375
2. **Static node interception in `_start_node_task` and `DynamicNodeScheduler`** —
359376
when `_schedule_ready_nodes` pops a trigger for a static node,
360-
`_start_node_task` looks up `recovered = loop_state.recovered_executions.get(f"{node_name}@{run_id}")`:
361-
- If `recovered` is present, `_start_node_task` calls
362-
`check_interception(node=node, recovered=recovered)` to check whether the
377+
`_start_node_task` looks up or creates `run = loop_state.runs[node_path]`,
378+
sets `run.is_static = True`, and registers `loop_state.static_runs[node_name] = run`:
379+
- If `run.recovered_state` is present, `_start_node_task` uses
380+
`_classify_static_replay` (`check_interception`) to determine whether the
363381
run will fast-forward (`not result.should_run` and not a resolved transfer
364382
interrupt), adding `node_name` to `loop_state.replayed_nodes` (so
365383
checkpoint emission is skipped in `_schedule_ready_nodes` and on the
366384
`COMPLETED` path of `_handle_completion`; `_handle_completion` still emits
367-
a checkpoint if a replayed node comes back `WAITING`) and seeding
368-
`loop_state.runs[node_path]` with
369-
`DynamicNodeRun(state=NodeState(run_id=run_id), recovered_state=recovered, is_static=True)`.
385+
a checkpoint if a replayed node comes back `WAITING`).
386+
`_at_concurrency_limit` excludes `replayed_nodes` from the
387+
`max_concurrency` count. A resolved-transfer fast-forward is not in that
388+
set because it runs its transfer target once the replay barrier releases
389+
it, so under `max_concurrency` `_schedule_ready_nodes` keeps its trigger
390+
buffered (`_is_held_transfer`) until its barrier key is released and then
391+
counts it like any running node. If nothing else is pending, it starts
392+
one held node anyway so the barrier reports the divergence.
370393
- `_start_node_task` then dispatches `ctx._run_node_internal` to
371394
`DynamicNodeScheduler._check_existing_run`, which runs
372395
`check_interception(node=curr_node, recovered=run.recovered_state, current_run=run)`:
@@ -377,25 +400,30 @@ stages:
377400
- **Completed non-`Workflow` node (or `rerun_on_resume=False` with all interrupts resolved)**:
378401
returns `should_run=False`; `_check_existing_run` builds a mock
379402
`Context` (`create_mock_context`) and awaits
380-
`ReplayManager.wait_sequence` so `_handle_completion` can re-surface
381-
replayed output (`_maybe_reemit_replayed_output`) and buffer downstream
382-
triggers without running `NodeRunner`.
403+
`ReplayManager.wait_sequence` so `_handle_completion` can record the
404+
outcome on `run`, re-surface replayed output
405+
(`_maybe_reemit_replayed_output`), and buffer downstream triggers without
406+
running `NodeRunner`.
383407
- **Interrupted with unresolved interrupts**: if `rerun_on_resume=True`
384408
and `recovered.resolved_ids` is non-empty (**partial resume**),
409+
fast-forwards (`should_run=False`) with the rehydrated `output`,
410+
`route`, and `transfer_to_agent` when `recovered.finished_after_resume`
411+
is `True` (and a result was recorded or `not node.wait_for_output`), or
385412
re-executes (`should_run=True`) via `NodeRunner` with
386-
`resume_inputs=recovered.resolved_responses`; otherwise stays WAITING
387-
(`should_run=False` with `interrupts` populated) and records unresolved
388-
IDs in `_LoopState.interrupt_ids`.
413+
`resume_inputs=recovered.resolved_responses` otherwise; if not a partial
414+
resume on a `rerun_on_resume` node, stays WAITING (`should_run=False`
415+
with `interrupts` populated) and records unresolved IDs in
416+
`_LoopState.interrupt_ids`.
389417
- **Interrupted with all interrupts resolved (`rerun_on_resume=True`) or prior failure (`error_code`)**:
390418
re-executes (`should_run=True`) via `NodeRunner` with
391419
`resume_inputs=recovered.resolved_responses`.
392-
3. **Dynamic node lazy rehydration (`_rehydrate_from_events`)** — dynamic
393-
children are not scanned upfront into `recovered_executions`. When a
394-
re-executing parent calls `ctx.run_node()`,
395-
`DynamicNodeScheduler._execute_step` lazily populates
396-
`_LoopState.runs[node_path]` via `_rehydrate_from_events` and applies the
397-
same `check_interception` rules in `_check_existing_run` (with
398-
`current_run=run` also deduplicating same-turn completed or waiting runs).
420+
3. **Dynamic node lazy rehydration (`_rehydrate_from_events`)** — descendant
421+
dynamic children not already present in `_LoopState.runs` are lazily
422+
rehydrated when a re-executing parent calls `ctx.run_node()`.
423+
`DynamicNodeScheduler._execute_step` populates `_LoopState.runs[node_path]`
424+
via `_rehydrate_from_events` and applies the same `check_interception` rules
425+
in `_check_existing_run` (with `current_run=run` also deduplicating
426+
same-turn completed or waiting runs).
399427

400428
## Key design rules for node authors
401429

‎.agents/skills/adk-debug/references/failure-modes.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -91,18 +91,19 @@ A synchronous tool function is awaited inline on the event loop, so anything
9191
blocking inside it — a `requests` call, `time.sleep`, a large file read —
9292
freezes the entire run, not just that tool.
9393

94-
Make the tool `async`. In live mode only, you can instead hand tools to a thread
95-
pool:
94+
Make the callable `async`, or hand synchronous `FunctionTool` and `FunctionNode`
95+
callables (and all tools in live mode) to a thread pool:
9696

9797
```python
9898
from google.adk.agents.run_config import RunConfig, ToolThreadPoolConfig
9999

100100
run_config = RunConfig(tool_thread_pool_config=ToolThreadPoolConfig()) # 4 workers
101101
```
102102

103-
Source: `FunctionTool._invoke_callable` in
104-
`src/google/adk/tools/function_tool.py`,
105-
`_call_tool_in_thread_pool` in `src/google/adk/flows/llm_flows/functions.py`.
103+
Source: `_resolve_sync_callable_runner` in
104+
`src/google/adk/utils/_sync_runner.py`, `FunctionTool._invoke_callable` in
105+
`src/google/adk/tools/function_tool.py`, and `_call_tool_in_thread_pool` in
106+
`src/google/adk/flows/llm_flows/tools/_thread_pool.py`.
106107

107108
## The run stops early and nothing looks wrong
108109

‎.agents/skills/adk-style/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ surfacing in review. Read the one reference for the topic you are touching.
2626
| --- | --- |
2727
| Adding a `.py` file; deciding public vs private; `__init__.py` and `__all__` | [visibility.md](references/visibility.md) |
2828
| Writing `import` lines; relative vs absolute; circular imports; `TYPE_CHECKING`; lazy imports | [imports.md](references/imports.md) |
29-
| Annotating args and returns; `AgentMode` vs raw mode strings; `_NodePathBuilder`, `_BranchPath`, and `build_node`; `Optional` vs `\| None`; keyword-only args; `isinstance`; asserts; mypy; `# type: ignore` and `cast` | [typing.md](references/typing.md) |
29+
| Annotating args and returns; `AgentMode` vs raw mode strings; `_NodePathBuilder`, `_BranchPath`, and `build_node`; `X \| None` and `X \| Y` instead of `Optional` and `Union`; keyword-only args; `isinstance`; asserts; mypy; `# type: ignore` and `cast` | [typing.md](references/typing.md) |
3030
| Defining a Pydantic model, validator, private attribute, or on-wire payload | [pydantic.md](references/pydantic.md) |
3131
| Indentation, line length, quotes; running the formatter; what each hook checks | [formatting.md](references/formatting.md) |
3232
| Writing a docstring or an explanatory comment | [documentation.md](references/documentation.md) |

‎.agents/skills/adk-style/references/imports.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,13 @@
2121
## One name per line
2222

2323
`isort`'s `google` profile puts every imported name on its own line, so
24-
`from typing import Any, Optional` becomes two lines. Ordering is
24+
`from typing import Any, Literal` becomes two lines. Ordering is
2525
case-insensitive and does not group by type, which is why `PrivateAttr` sorts
2626
after `model_validator`:
2727

2828
```python
2929
from typing import Any
30-
from typing import Optional
30+
from typing import Literal
3131

3232
from pydantic import BaseModel
3333
from pydantic import Field

‎.agents/skills/adk-style/references/pydantic.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ Declare bounds on the field rather than writing a validator for them — it
3232
keeps the rule next to the data and shows up in the generated JSON schema.
3333

3434
```python
35-
compaction_interval: Optional[int] = Field(default=None, gt=0)
35+
compaction_interval: int | None = Field(default=None, gt=0)
3636
injected_latency_seconds: float = Field(default=0.0, le=120.0)
3737
```
3838

@@ -42,7 +42,7 @@ The house style is an attribute docstring directly under the field, which
4242
Sphinx picks up:
4343

4444
```python
45-
model: Union[str, BaseLlm] = ''
45+
model: str | BaseLlm = ''
4646
"""The model to use for the agent.
4747
4848
When not set, the agent inherits the model from its ancestor.

0 commit comments

Comments
 (0)