Merge branch 'main' into feat/session-merge-state

Author: rohityan

.agents/skills/adk-architecture/SKILL.md

@@ -11,7 +11,7 @@ description: ADK architectural knowledge — graph orchestration, resumption, ex
 - [Runner](references/interfaces/runner.md) — The public interface for executing workflows and agents. Documents entrance methods `run` and `run_async`.
 - [Agent](references/interfaces/agent.md) — Blueprint defining identity, instructions, and tools. Documents that `run` is the preferred entrance method.
 - [BaseAgent](references/interfaces/base-agent.md) — Base class for all agents. Defines the contract for subclassing with `_run_impl` as the primary override point.
-- [Event](references/interfaces/event.md) — Core data structure for state reconstruction and communication. Represents a conversation turn or action.
+- [Event](references/interfaces/event.md) — Core data structure for state reconstruction and communication. Represents a conversation turn, action, and state lifecycle immutability.
 
 ## Key Principles (references/principles/)
 - [API Principles](references/principles/api-principles.md) — stability, backward compatibility, and self-containment. Use when making design choices that affect the public API surface.

.agents/skills/adk-architecture/references/architecture/observability.md

@@ -30,7 +30,7 @@ execution flow).
 implicit "current span" context. In a concurrent asyncio.Task
 runtime, implicit context can be unreliable across concurrent
 nodes. All tracing operations (attributes, logs, child spans)
-should go through `ctx._span`.
+should go through `ctx._span`. When attaching or detaching OTel context explicitly (e.g., using `context.attach()` and `context.detach()`), **always pair them inside a `try...finally` block** to prevent context leaks across requests.
 
 **Span lifecycle:**
 

.agents/skills/adk-architecture/references/architecture/workflow-resumability.md

@@ -0,0 +1,125 @@
+# Workflow Resumability: Model and Direction
+
+This note describes how a `Workflow` node preserves and restores execution state
+across a human-in-the-loop pause, how that compares to peer agent frameworks,
+and the direction we are moving in. It complements `checkpoint-resume.md`, which
+covers the interrupt/resume lifecycle for a single node.
+
+The first thing to be clear about: a `Workflow` reconstructs its progress from
+the session event stream on every run, so it resumes whether or not resumability
+is configured. The `is_resumable` flag does not switch resume on or off. What it
+switches on is **durability** — persisting loadable checkpoints and letting an
+invocation be continued across separate runner calls.
+
+## Current model
+
+### Resume is always on: reconstruction by event replay
+
+On every run, the workflow scans the current invocation's session events and
+rebuilds its in-memory loop state (which nodes completed, their outputs, which
+are still waiting on interrupts). Completed nodes are fast-forwarded from their
+recovered output rather than re-executed; the interrupted node re-runs with the
+supplied responses.
+
+This path (`_run_impl` -> `ReplayManager.scan_workflow_events`) has no
+`is_resumable` guard — the scan matches events purely by invocation id. The loop
+state is not persisted and there is no separate workflow checkpoint to load; the
+session event log is the source of truth. So within an invocation, a workflow is
+inherently replay-resumable, flag or no flag. This is exactly what deanchen
+means by "still resumable even when resumability is not set."
+
+### What `is_resumable` actually adds: durability
+
+`ResumabilityConfig.is_resumable` is a durability switch. When it is set:
+
+1.  **Cross-call resume.** The runner will continue an existing invocation
+    without a fresh user message and set up a "resumed invocation" context,
+    rehydrating the recorded agent state and end-of-agent markers from history.
+    With the flag off, the runner requires a new message and starts a fresh
+    invocation instead.
+2.  **Checkpoint markers in the log.** Composite agents (`LlmAgent`,
+    `SequentialAgent`, `LoopAgent`, `ParallelAgent`, and `LlmAgent`s wrapped as
+    workflow nodes) write `agent_state` / `end_of_agent` events into the session
+    only when the invocation is resumable. These make progress loadable across a
+    process boundary.
+3.  **Function-response routing.** Routing an incoming function response back to
+    its originating invocation is enabled only when resumable.
+
+The config's own definition is durability-shaped: pause an invocation on a
+long-running call, and resume it from the last event if it paused or failed
+midway, best-effort and at-least-once, with in-memory state lost. So the
+accurate statement is: the flag decides whether progress is persisted as
+loadable checkpoints and whether an invocation can be resumed across runner
+calls — not whether the workflow can resume. Resumability here is really
+durability.
+
+### The `Workflow` node emits no checkpoint of its own
+
+Today the `Workflow` node does not persist a node-status checkpoint (a `nodes`
+payload of statuses/outputs). It relies solely on event replay. The `nodes`
+shape exists only as an input to graph visualization, not as something the
+runtime writes during a run. The only checkpoint events on the workflow path
+come from wrapped composite agents emitting their own `agent_state`, and those
+are gated on the flag as above.
+
+## How peer frameworks do it
+
+Every mainstream agent framework persists a **state snapshot with a position
+cursor** and, on resume, **loads that snapshot** — none reconstruct by replaying
+the entire history.
+
+Framework                | Durable unit                                                        | Position cursor                                                                    | Resume
+------------------------ | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------
+LangGraph (graph)        | `StateSnapshot` per super-step in a pluggable checkpointer          | `next` nodes + parent-pointer chain + per-task pending writes                      | re-invoke same thread id; load latest checkpoint, re-run only the interrupted node
+pydantic-graph (graph)   | `NodeSnapshot{state, node, status}` via a state-persistence backend | the snapshot's `node` = next node to run; `status` created/pending/running/success | `iter_from_persistence()` loads the next `created` snapshot
+OpenAI Agents SDK (loop) | serialized `RunState` blob                                          | run cursor inside the state; correlate by tool-call id                             | deserialize the state, apply approvals, resume the run
+Pydantic AI (loop)       | message history + deferred-tool results                             | implicit in the transcript; correlate by tool-call id                              | new run over the prior message history
+
+ADK's durable unit today is the event log itself, and resume is by replay over
+it. Two patterns from the peers are worth copying, both consistent across them:
+
+-   **A snapshot is the source of truth for resume.** The runtime writes a
+    snapshot as it advances and reads the latest one to continue. Resume cost is
+    bounded by the snapshot size, not by history length.
+-   **Resume re-runs the paused unit from its start** (LangGraph and
+    pydantic-graph both re-execute the whole node, not a saved program counter),
+    which keeps the durable state small and pushes an idempotency contract onto
+    the node author — the same at-least-once contract ADK already documents.
+
+## Direction: persist a workflow checkpoint as the durable source of truth
+
+Even with durability on, the `Workflow` node reloads by replaying the event
+history rather than loading a compact checkpoint. The direction — peer-aligned,
+and the one ADK's own composite agents already follow — is to persist a workflow
+checkpoint and load the latest one on resume:
+
+-   As the workflow advances, persist node statuses and outputs as a checkpoint
+    (an `agent_state` payload), the way composite agents already persist theirs.
+-   On resume, seed the loop state from the most recent checkpoint, then
+    continue: re-run only the interrupted node and dispatch newly-ready
+    successors.
+-   This makes resume cost independent of history length and unifies the
+    `Workflow` node with composite agents and with LangGraph / pydantic-graph /
+    the OpenAI SDK.
+
+This only applies when durability is on. Without `is_resumable` there is nothing
+to persist, and the workflow continues to resume within an invocation by replay
+as it does today.
+
+## Open considerations
+
+-   **Payload completeness.** A workflow checkpoint must carry (or be able to
+    recover) each completed node's output, run id, and branch — the equivalent
+    of LangGraph's per-task pending writes — to fully replace event replay.
+-   **Partial interrupt resolution.** A node with several interrupts may receive
+    only some responses on a resume. The re-run-vs-wait behavior differs between
+    an orchestrating node (re-run to dispatch the resolved branch) and a leaf
+    node (wait for all), keyed on `rerun_on_resume`. This is decided in the
+    shared replay-interception logic and should be settled before a load path
+    relies on it.
+-   **Versioning.** Long-lived paused runs can outlive a code change. A version
+    marker on the checkpoint lets a resume route to a compatible code path (the
+    OpenAI SDK makes this an explicit recommendation).
+-   **Serialization.** Keep payloads JSON-serializable (Pydantic `model_dump`),
+    so any persistence backend works and no code objects are serialized; node
+    objects are rebound from the in-memory graph definition on resume.

.agents/skills/adk-architecture/references/interfaces/event.md

@@ -23,3 +23,8 @@ The `Event` class represents a single event in the conversation history or workf
 - `get_function_calls()`: Returns function calls in the event.
 - `get_function_responses()`: Returns function responses in the event.
 - `is_final_response()`: Returns whether the event is the final response of an agent.
+
+## State Lifecycle & Immutability
+- **Event Immutability**: Event history is immutable. Never assume that events are mutated or cleared after they are saved to a session.
+- **Signal & Action Persistence**: When checking if a signal or action is "pending" versus "resolved", do not rely on events being modified in place.
+- **Compaction Side-Effects**: Be aware that storing stateful flags on events (such as requested actions or transient status) can have permanent unintended effects on background compaction when those events age but remain in history.

.agents/skills/adk-sample-creator/SKILL.md

@@ -89,7 +89,7 @@ Each sample should have a `README.md` with the following structure:
 
 - **Overview**: What the sample does.
 - **Sample Inputs**: Examples of inputs to test with. Each prompt must be wrapped in backticks. If a prompt has an explanation, always add a blank line between the prompt and the explanation, and indent the explanation by two spaces.
-- **Graph**: Visualization of the graph flow (Mermaid recommended). For Workflow root agents, visualize the graph flow of nodes. For LlmAgent root agents that orchestrate tools or sub-agents, visualize the topology of the agent and its tools/sub-agents instead of internal workflow nodes.
+- **Graph**: Visualization of the graph flow (Mermaid recommended). For Workflow root agents, visualize the graph flow of nodes. For agents that orchestrate tools or sub-agents (e.g., `LlmAgent`, `ManagedAgent`), visualize the topology of the agent and its tools/sub-agents instead of internal workflow nodes. Keep it a simple topology diagram (a few nodes and edges). Do **not** draw a request/response data-flow sequence (e.g., `user -> agent -> API -> tool -> ... -> user`); those are noisy and add little value over the topology.
 - **How To**: Explanation of key techniques used (e.g., `ctx.run_node`).
 - **Related Guides**: Links to relevant developer guides in `docs/guides/` that explain the concepts or classes used.
 
@@ -118,7 +118,7 @@ graph TD
     START --> MyNode
 ```
 
-For LlmAgent root agents:
+For agents that orchestrate tools or sub-agents (`LlmAgent`, `ManagedAgent`, ...):
 ```mermaid
 graph TD
     MyAgent[my_agent] -->|calls| MyTool(my_tool)

.agents/skills/adk-style/references/typing.md

@@ -48,3 +48,7 @@ Use `isinstance()` for runtime type discrimination when handling polymorphic inp
 - Always include an `else` branch that raises `TypeError` or handles the unknown case.
 - Prefer `isinstance(x, SomeType)` over `type(x) is SomeType` — it handles subclasses correctly.
 - For checking multiple types: `isinstance(x, (TypeA, TypeB))`.
+
+## No Asserts in Production Code
+
+**Never use `assert` statements in production code.** They can be optimized away when Python runs with `-O` flags and provide poor error messages. Use specific exceptions like `ValueError`, `TypeError`, or `RuntimeError` instead.

.agents/skills/adk-verify-snippets/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: adk-verify-snippets
+description: >
+  Extracts and verifies the runnability and code coverage of all Python code blocks inside a Markdown file.
+  Generates a detailed compilation and execution report.
+metadata:
+  author: Antigravity
+  version: 1.4.0
+---
+
+# Verify Markdown Snippets Skill
+
+This skill extracts all ` ```python ` blocks from a Markdown file, executes each
+one in a process-isolated environment using the bundled `run.py` harness, and
+generates a structured report covering load status, run status, and line
+coverage.
+
+> [!CAUTION] **STRICT READ-ONLY CONSTRAINT — READ THIS BEFORE DOING ANYTHING
+> ELSE**
+>
+> This skill is **read-only**. The agent **MUST NOT**: - **Modify** any file in
+> the repository (source, test, config, docs, or skill files — including this
+> SKILL.md). - **Delete** any file in the repository. - **Create** any new file
+> in the repository.
+>
+> The **only two write operations permitted** are: 1. Writing temporary `.py`
+> snippet files to a **system temp directory outside the repository**. 2.
+> Writing the final `<filename>_REPORT.md` into the **same directory as the
+> source Markdown file**.
+>
+> If in doubt, do not write. Any other mutation is a violation of this skill's
+> contract.
+
+--------------------------------------------------------------------------------
+
+## 🔧 Prerequisites
+
+1.  **ADK Python environment**: Run from the repository root with the `uv`
+    virtual environment active.
+2.  **`coverage` package** *(optional)*: Enables per-snippet coverage reporting.
+    Without it, coverage columns show `—`.
+
+    ```bash
+    uv pip install coverage
+    ```
+
+3.  **Gemini API key**: Required only for snippets that instantiate an `Agent`,
+    `App`, or `Workflow` (which make live Gemini API calls). Set one of:
+
+    ```bash
+    export GEMINI_API_KEY="your-key-here"
+    # or
+    export GOOGLE_API_KEY="your-key-here"
+    ```
+
+    If both are set, `GEMINI_API_KEY` takes precedence.
+
+--------------------------------------------------------------------------------
+
+## 🛠️ Usage
+
+```bash
+uv run --no-sync python .agents/skills/adk-verify-snippets/scripts/verify_md.py <path_to_markdown_file.md>
+```
+
+The script prints progress for each snippet, then writes a report to
+**`<filename>_REPORT.md`** in the same directory as the source file and prints
+the full path on completion.
+
+**Report contents:** :- **Executive Summary table** — one row per snippet:
+preceding heading, Load phase status, Run phase status, coverage %, and error
+detail.
+
+-   **Detailed section** — for each snippet: the extracted code block, full
+    execution logs (stdout + stderr/traceback), and the coverage report.
+
+--------------------------------------------------------------------------------
+
+## 📝 How Snippets Are Classified
+
+Each ` ```python ` block falls into one of these categories:
+
+### 1. Runnability Test (has a module-level ADK component)
+
+If the snippet assigns a `Workflow`, `Agent`, or `App` to a **module-level
+variable**, the runner executes it against the Gemini API.
+
+-   The variable name does not matter — the runner finds it automatically via
+    `vars(module)`.
+-   For multi-agent snippets, the runner identifies the root agent by excluding
+    any agent that appears in another agent's `sub_agents` list.
+-   To use a custom test prompt instead of the default `"Test input topic"`,
+    define a module-level `test_input` string in the snippet.
+
+If no module-level ADK component is found, the run phase is skipped and the
+report shows `➖ NO ADK COMPONENT`.
+
+### 2. Loadability-Only (no ADK component)
+
+The runner verifies the snippet compiles and imports without error. No API call
+is made.
+
+### 3. Skipped (annotated with ignore)
+
+Place `<!-- verify-snippets: ignore -->` immediately before the opening
+` ```python ` fence to exclude a block entirely. Use this for pseudo-code,
+illustrative examples, or snippets that require external setup.
+
+````markdown
+<!-- verify-snippets: ignore -->
+```python
+# pseudo-code — not runnable as-is
+my_agent = Agent(model="gemini-ultra-hypothetical", ...)
+```
+````
+
+The report shows these as `⏭️ SKIPPED`.
+
+--------------------------------------------------------------------------------
+
+## ⚠️ Known Limitations
+
+-   **No shared state between snippets**: Each snippet runs in a fresh
+    subprocess with no imports or variables carried over from previous snippets.
+    A snippet that depends on code from an earlier block will fail with
+    `NameError` or `ImportError`. Make each snippet self-contained, or annotate
+    it with `<!-- verify-snippets: ignore -->`.
+-   **120-second timeout**: Each snippet is killed after 120 seconds. Annotate
+    long-running or blocking snippets with `<!-- verify-snippets: ignore -->`.
+-   **Ignore annotation placement**: The `<!-- verify-snippets: ignore -->`
+    annotation applies to the next ` ```python ` fence encountered. Blank lines
+    between the annotation and the fence are tolerated, but any non-blank line
+    (prose or a heading) cancels the annotation.
+-   **Bare ` ``` ` closes the block**: The parser closes a Python block on the
+    first bare ` ``` ` line (no language tag). A bare ` ``` ` appearing as
+    content inside a snippet (e.g. to demonstrate Markdown syntax) will
+    prematurely close the block. Annotate such snippets with
+    `<!-- verify-snippets: ignore -->`.
+
+--------------------------------------------------------------------------------
+
+## ⚠️ Behavioral Constraints (For AI Agents)
+
+-   **Read-only**: See the caution block at the top. The constraint is absolute.
+-   **Report only, do not fix**: The agent MUST NOT rewrite the source Markdown,
+    modify code blocks, or generate patches. Present the summary table to the
+    user and stop.
+-   **Present the summary table verbatim**: After the script completes, read the
+    generated `_REPORT.md` and copy the Executive Summary table to the user
+    **exactly as written** — same six columns, same order, no renaming or
+    dropping: `Snippet | Preceding Heading | Load Phase | Run Phase | Coverage |
+    Details`