chore: import upstream snapshot with attribution

contributing/samples/core/app/README.md

@@ -0,0 +1,91 @@
+# Application Configuration (App)
+
+## Overview
+
+This sample demonstrates how to configure an `App` in ADK. An `App` serves as the top-level container for an agentic system, wrapping a root agent or workflow and providing application-wide configurations such as plugins, event compaction, and context caching.
+
+## Sample Inputs
+
+- `Hello, who are you?`
+
+  *The application executes `greeter_agent`. The `CountInvocationPlugin` logs the agent and LLM run counts to the console.*
+
+- `Can you help me plan a trip?`
+
+  *As the conversation continues, event compaction automatically summarizes past turns every 2 invocations, while context caching optimizes token usage.*
+
+## Graph
+
+```mermaid
+graph TD
+    User[User Input] --> AppContainer[App: app]
+    subgraph AppContainer [App Container]
+        Plugins[Plugins: CountInvocation, SaveFilesAsArtifacts] --> GreeterAgent[root_agent: greeter_agent]
+        GreeterAgent --> Configs[Configs: EventCompaction, ContextCache]
+    end
+    AppContainer --> Response[User Response]
+```
+
+## How To
+
+### Wrapping an Agent in an App
+
+To configure application-level behaviors, instantiate an `App` object and pass your root agent to the `root_agent` parameter:
+
+```python
+from google.adk import Agent
+from google.adk.apps.app import App
+
+root_agent = Agent(
+    name="greeter_agent",
+    instruction="You are a friendly assistant.",
+)
+
+app = App(
+    name="app",
+    root_agent=root_agent,
+)
+```
+
+### Configuring Application Plugins
+
+Plugins provide cross-cutting capabilities (such as telemetry, custom logging, or artifact saving) across the entire application. Pass a list of plugin instances to `plugins`:
+
+```python
+from google.adk.plugins.save_files_as_artifacts_plugin import SaveFilesAsArtifactsPlugin
+
+app = App(
+    name="app",
+    root_agent=root_agent,
+    plugins=[
+        CountInvocationPlugin(),
+        SaveFilesAsArtifactsPlugin(),
+    ],
+)
+```
+
+### Configuring Event Compaction and Caching
+
+The `App` container is also where you define long-term session behavior and optimization strategies:
+
+- **`events_compaction_config`**: Manages token usage by periodically summarizing older turns in a session.
+- **`context_cache_config`**: Enables prompt caching across invocations to reduce latency and cost.
+
+```python
+from google.adk.apps.app import EventsCompactionConfig
+from google.adk.agents.context_cache_config import ContextCacheConfig
+
+app = App(
+    name="app",
+    root_agent=root_agent,
+    events_compaction_config=EventsCompactionConfig(
+        compaction_interval=2,
+        overlap_size=1,
+    ),
+    context_cache_config=ContextCacheConfig(
+        cache_intervals=10,
+        ttl_seconds=1800,
+        min_tokens=1000,
+    ),
+)
+```

contributing/samples/core/app/agent.py

@@ -0,0 +1,76 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from google.adk import Agent
+from google.adk.agents.base_agent import BaseAgent
+from google.adk.agents.callback_context import CallbackContext
+from google.adk.agents.context_cache_config import ContextCacheConfig
+from google.adk.apps.app import App
+from google.adk.apps.app import EventsCompactionConfig
+from google.adk.models.llm_request import LlmRequest
+from google.adk.plugins.base_plugin import BasePlugin
+from google.adk.plugins.save_files_as_artifacts_plugin import SaveFilesAsArtifactsPlugin
+
+
+class CountInvocationPlugin(BasePlugin):
+  """A custom plugin that counts agent and LLM invocations."""
+
+  def __init__(self) -> None:
+    """Initialize the plugin with counters."""
+    super().__init__(name="count_invocation")
+    self.agent_count: int = 0
+    self.llm_request_count: int = 0
+
+  async def before_agent_callback(
+      self, *, agent: BaseAgent, callback_context: CallbackContext
+  ) -> None:
+    """Count agent runs."""
+    self.agent_count += 1
+    print(f"[Plugin] Agent run count: {self.agent_count}")
+
+  async def before_model_callback(
+      self, *, callback_context: CallbackContext, llm_request: LlmRequest
+  ) -> None:
+    """Count LLM requests."""
+    self.llm_request_count += 1
+    print(f"[Plugin] LLM request count: {self.llm_request_count}")
+
+
+root_agent = Agent(
+    name="greeter_agent",
+    instruction="""\
+You are a friendly and helpful concierge assistant. Greet the user and answer their questions.
+""",
+)
+
+
+app = App(
+    name="app",
+    root_agent=root_agent,
+    plugins=[
+        CountInvocationPlugin(),
+        SaveFilesAsArtifactsPlugin(),
+    ],
+    events_compaction_config=EventsCompactionConfig(
+        compaction_interval=2,
+        overlap_size=1,
+    ),
+    context_cache_config=ContextCacheConfig(
+        cache_intervals=10,
+        ttl_seconds=1800,
+        min_tokens=1000,
+    ),
+)

contributing/samples/core/app/tests/hello.json

@@ -0,0 +1,37 @@
+{
+  "events": [
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "text": "Hello, who are you?"
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-1",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
+    {
+      "author": "greeter_agent",
+      "content": {
+        "parts": [
+          {
+            "text": "Hello there! I'm a friendly and helpful concierge assistant, ready to answer your questions. My internal name is `greeter_agent`. How can I assist you today?"
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-2",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "greeter_agent@1"
+      }
+    }
+  ]
+}

contributing/samples/core/app/tests/help_trip.json

@@ -0,0 +1,37 @@
+{
+  "events": [
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "text": "Can you help me plan a trip?"
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-1",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
+    {
+      "author": "greeter_agent",
+      "content": {
+        "parts": [
+          {
+            "text": "Hello there! I'd be absolutely delighted to help you plan your trip. To get started, I'll need a little more information.\n\nCould you tell me:\n\n1.  **Where are you hoping to go?** (e.g., a specific city, country, or region)\n2.  **When are you planning to travel?** (e.g., specific dates, a season, or a general time of year)\n3.  **What kind of trip are you envisioning?** (e.g., a relaxing beach vacation, an adventurous hiking trip, a cultural city break, a family holiday, etc.)\n4.  **Who are you traveling with?** (e.g., solo, with a partner, family with kids, friends)\n5.  **Do you have any specific interests or preferences?** (e.g., food, history, art, nature, nightlife, budget considerations)\n\nThe more details you can provide, the better I can assist you in creating an amazing itinerary!"
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-2",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "greeter_agent@1"
+      }
+    }
+  ]
+}

contributing/samples/core/app/tests/who_are_you.json

@@ -0,0 +1,37 @@
+{
+  "events": [
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "text": "Who are you?"
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-1",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
+    {
+      "author": "greeter_agent",
+      "content": {
+        "parts": [
+          {
+            "text": "Hello there! I'm a friendly and helpful concierge assistant. How can I assist you today?"
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-2",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "greeter_agent@1"
+      }
+    }
+  ]
+}