examples: standardize directory entrypoints (#3259)

Co-authored-by: openhands <openhands@all-hands.dev>

Author: xingyaoww

.agents/skills/custom-codereview-guide.md

@@ -124,6 +124,7 @@ If the updated package was uploaded **within the last 7 days**, treat it as a re
 - **Breaking Changes**: API changes affecting users, removed public fields/methods, changed defaults
 - **Code Quality**: Code duplication, missing comments for non-obvious decisions, inline imports (unless necessary for circular deps)
 - **Repository Conventions**: Use `pyright` not `mypy`, put fixtures in `conftest.py`, avoid `sys.path.insert` hacks
+- **Directory Example Entrypoints**: PRs that add or modify folder-based runnable examples under `examples/` should use `main.py` as the entrypoint and add the directory to `_TARGET_DIRECTORIES` in `tests/examples/test_examples.py`; see [Directory-Based Examples](#directory-based-examples)
 - **Event Type Deprecation**: Changes to event types (Pydantic models used in serialization) must handle deprecated fields properly
 - **Thread Safety**: New methods in `LocalConversation` that read or write `self._state` must use `with self._state:` — see the [Concurrency](#concurrency---localconversation-state-lock) section below
 - **Persistence Paths**: Code that computes persistence directories must not double-append the conversation hex — see the [Persistence Paths](#persistence-path-construction) section below
@@ -132,6 +133,18 @@ If the updated package was uploaded **within the last 7 days**, treat it as a re
 - **Secret Serialization**: Fields that carry secrets must use `serialize_secret()` from `openhands.sdk.utils.pydantic_secrets`. For `dict[str, str]` secret fields, wrap each value in `SecretStr` and call `serialize_secret` per value. Do not hand-roll redaction logic (e.g. custom sentinels or inline `expose_secrets` checks) in field serializers
 - **Info-Log Payloads**: `logger.info(...)` must not dump objects, dicts, or variable-length lists — see [Logging Hygiene](#logging-hygiene)
 
+## Directory-Based Examples
+
+When a PR adds or modifies a runnable example represented by a directory under `examples/`, verify that:
+
+1. The runnable entrypoint is named `main.py`.
+2. Helper modules inside that directory are not accidentally treated as standalone examples.
+3. `tests/examples/test_examples.py` includes the example directory in `_TARGET_DIRECTORIES` when the example should run in the `test-examples` workflow.
+4. The example prints an `EXAMPLE_COST: ...` marker when run by the workflow.
+
+Do not ask for this convention on support scripts that are intentionally named for GitHub workflow consumption (for example reusable automation scripts under `examples/03_github_workflows/`) unless they are presented as a directory-based runnable example.
+
+
 ## Event Type Deprecation - Critical Review Checkpoint
 
 When reviewing PRs that modify event types (e.g., `TextContent`, `Message`, `Event`, or any Pydantic model used in event serialization), **DO NOT APPROVE** until the following are verified:

AGENTS.md

@@ -114,6 +114,7 @@ When reviewing code, provide constructive feedback:
 - AgentSkills progressive disclosure goes through `AgentContext.get_system_message_suffix()` into `<available_skills>`, and `openhands.sdk.context.skills.to_prompt()` truncates each prompt description to 1024 characters because the AgentSkills specification caps `description` at 1-1024 characters.
 - Workspace-wide uv resolver guardrails belong in the repository root `[tool.uv]` table. When `exclude-newer` is configured there, `uv lock` persists it into the root `uv.lock` `[options]` section as both an absolute cutoff and `exclude-newer-span`, and `uv sync --frozen` continues to use that locked workspace state.
 - `pr-review-by-openhands` delegates to `OpenHands/extensions/plugins/pr-review@main`. Repo-specific reviewer instructions live in `.agents/skills/custom-codereview-guide.md`, and because task-trigger matching is substring-based, that `/codereview` skill is also auto-injected for the workflow's `/codereview-roasted` prompt.
+- Directory-based runnable examples under `examples/` should expose their entrypoint as `main.py`, and `tests/examples/test_examples.py` should explicitly list the example directory in `_TARGET_DIRECTORIES` so the non-recursive example workflow collects it without accidentally running helper modules.
 - The duplicate-issue automation scripts should validate `owner/repo` arguments before interpolating GitHub API paths, handle per-issue auto-close failures without aborting the whole batch, and keep `app_conversation_id` paths unquoted because OpenHands conversation IDs are already canonicalized for those endpoints.
 - `agent-server` now defaults `TMUX_TMPDIR` to a per-process directory under the system temp dir (`openhands-agent-server-<pid>`) when the environment variable is unset. This isolates tmux sockets/cleanup across concurrent server instances while still respecting an explicit `TMUX_TMPDIR` override.
 - Conversation worktrees for git-backed local workspaces live under `/tmp/conversation-worktrees/<conversation_id>/<repo_root.name>`, and if the original workspace points at a subdirectory inside the repo, the active workspace should preserve that relative path inside the worktree.

examples/01_standalone_sdk/33_hooks/README.md

@@ -4,7 +4,7 @@ This folder demonstrates the OpenHands hooks system.
 
 ## Example
 
-- **33_hooks.py** - Complete hooks demo showing all four hook types
+- **main.py** - Complete hooks demo showing all four hook types
 
 ## Scripts
 
@@ -24,7 +24,7 @@ export LLM_MODEL="anthropic/claude-sonnet-4-5-20250929"  # optional
 export LLM_BASE_URL="https://your-endpoint"  # optional
 
 # Run example
-python 33_hooks.py
+python main.py
 ```
 
 ## Hook Types

…s/01_standalone_sdk/33_hooks/33_hooks.py …mples/01_standalone_sdk/33_hooks/main.pyexamples/01_standalone_sdk/33_hooks/33_hooks.py renamed to examples/01_standalone_sdk/33_hooks/main.py examples/01_standalone_sdk/33_hooks/33_hooks.py renamed to examples/01_standalone_sdk/33_hooks/main.py

@@ -47,7 +47,7 @@ This pattern is useful for:
 - **`custom_tools/log_data.py`**: Example custom tool for logging structured data to JSON
 - **`Dockerfile`**: Simple Dockerfile that copies custom tools into the base image
 - **`build_custom_image.sh`**: Script to build the custom base image
-- **`custom_tool_example.py`**: SDK script demonstrating the full workflow
+- **`main.py`**: SDK script demonstrating the full workflow
 - **`README.md`**: This documentation
 
 ## The Custom Tool
@@ -106,7 +106,7 @@ When creating a conversation, the SDK:
 3. Server imports those modules, triggering auto-registration
 4. Tools become available for agent execution
 
-### 4. SDK Script (`custom_tool_example.py`)
+### 4. SDK Script (`main.py`)
 
 The script:
 - Builds the custom base image (if not already built)
@@ -133,7 +133,7 @@ The script:
 
 2. **Run the example**:
    ```bash
-   python custom_tool_example.py
+   python main.py
    ```
 
 The script will:

examples/02_remote_agent_server/06_custom_tool/README.md

@@ -26,8 +26,10 @@
     EXAMPLES_ROOT / "01_standalone_sdk",
     EXAMPLES_ROOT / "02_remote_agent_server",
     # These examples live under subdirectories (each with a single `main.py`).
+    EXAMPLES_ROOT / "01_standalone_sdk" / "33_hooks",
     EXAMPLES_ROOT / "01_standalone_sdk" / "37_llm_profile_store",
     EXAMPLES_ROOT / "01_standalone_sdk" / "43_mixed_marketplace_skills",
+    EXAMPLES_ROOT / "02_remote_agent_server" / "06_custom_tool",
     EXAMPLES_ROOT / "05_skills_and_plugins" / "01_loading_agentskills",
     EXAMPLES_ROOT / "05_skills_and_plugins" / "02_loading_plugins",
 )
@@ -88,9 +90,13 @@ def _normalize_path(path: Path) -> str:
 
 
 def test_directory_example_is_discovered() -> None:
+    assert (EXAMPLES_ROOT / "01_standalone_sdk" / "33_hooks" / "main.py") in EXAMPLES
     assert (
         EXAMPLES_ROOT / "01_standalone_sdk" / "37_llm_profile_store" / "main.py"
     ) in EXAMPLES
+    assert (
+        EXAMPLES_ROOT / "02_remote_agent_server" / "06_custom_tool" / "main.py"
+    ) in EXAMPLES
 
 
 @pytest.mark.parametrize("example_path", EXAMPLES, ids=_normalize_path)