@openhands/extensions 0.27.0 → 0.29.0

package/skills/linear/README.md

@@ -12,6 +12,8 @@ This skill is activated by the following keywords:
 
 ## Details
 
+Use authenticated Linear MCP tools first when they are available in the agent's environment. Detect the connection through tool availability rather than a particular server name. Fall back to the documented `LINEAR_API_KEY` and direct GraphQL flow when those tools are unavailable or raw API or `curl` access is explicitly needed.
+
 You need access to an environment variable, `LINEAR_API_KEY`, which allows you to interact with the Linear API.
 
 <IMPORTANT>

package/skills/linear/SKILL.md

@@ -9,16 +9,20 @@ triggers:
 
 # Linear
 
+## Connection selection
+
+Use authenticated Linear MCP tools first when they are available in the agent's environment. Detect this by tool availability, without depending on a particular MCP server name. Use the API key and direct GraphQL instructions below only when Linear MCP tools are unavailable or when raw API or `curl` access is explicitly needed.
+
 Windows PowerShell equivalents for the repeated Linear GraphQL `curl` and environment-variable snippets are in `references/windows.md`.
 
 <IMPORTANT>
-Before performing any Linear operations, check if the required environment variable is set:
+Before using the direct API fallback, check if the required environment variable is set:
 
 ```bash
 [ -n "$LINEAR_API_KEY" ] && echo "LINEAR_API_KEY is set" || echo "LINEAR_API_KEY is NOT set"
 ```
 
-If LINEAR_API_KEY is missing, ask the user to provide it before proceeding.
+If LINEAR_API_KEY is missing and authenticated Linear MCP tools are unavailable, ask the user to provide it before proceeding.
 </IMPORTANT>
 
 ## Understanding Linear Identifiers

package/skills/openhands-automation/README.md

@@ -16,13 +16,13 @@ This skill is activated by keywords:
 
 ## Features
 
-- **Prompt-based creation**: Create automations from a natural language prompt (recommended)
+- **Prompt-based creation**: Create automations from a natural language prompt, for tasks that benefit from agent reasoning
+- **Custom scripts**: Run your own code, with or without an LLM — the cheaper, more reliable fit for deterministic tasks (fixed data, scheduled HTTP calls, templated messages), and for custom dependencies or full control (see [references/custom-automation.md](references/custom-automation.md))
 - **Event-triggered automations**: Trigger on GitHub events (PR opened, issue commented, push, etc.)
 - **Custom webhooks**: Register webhooks for any service (Stripe, Slack, Linear, etc.)
 - **JMESPath filters**: Match events based on payload content (labels, mentions, repos)
 - **Automation management**: List, update, enable/disable, and delete automations
 - **Manual dispatch**: Trigger automation runs on-demand
-- **Custom automations**: For advanced users who need full control (see [references/custom-automation.md](references/custom-automation.md))
 
 ## API Base URL
 
@@ -30,6 +30,8 @@ Use an explicitly provided host first. When a local Agent Canvas automation serv
 
 ## Quick Start
 
+The examples below use the prompt preset, which suits tasks that need reasoning or judgment. For a deterministic task that needs no LLM, use a custom script instead — see the *Custom Script Example (No LLM)* in [SKILL.md](SKILL.md).
+
 ### Cron-Triggered Automation
 
 ```bash
@@ -81,9 +83,9 @@ curl -X POST "https://app.all-hands.dev/api/automation/v1/preset/prompt" \
   }'
 ```
 
-The service handles SDK code generation, tarball packaging, upload, and automation creation automatically.
+For preset automations, the service handles SDK code generation, tarball packaging, upload, and automation creation automatically.
 
 ## See Also
 
 - [SKILL.md](SKILL.md) — Full API reference, agent behavior rules, event keys, filters, and examples
-- [references/custom-automation.md](references/custom-automation.md) — Reference for custom automations with user-provided SDK scripts
+- [references/custom-automation.md](references/custom-automation.md) — Reference for custom automations with user-provided scripts, SDK-based or deterministic (no LLM)

package/skills/openhands-automation/SKILL.md

@@ -64,14 +64,14 @@ The agent server typically runs inside a **sandbox** (a Docker or Kubernetes con
 > 1. **For LLM-appropriate work, default to preset endpoints.** They handle all SDK boilerplate, tarball packaging, and upload automatically:
 >    - **Prompt preset** (`POST /v1/preset/prompt`) — for tasks expressed as a natural language prompt that benefit from agent reasoning
 >    - **Plugin preset** (`POST /v1/preset/plugin`) — when plugins with skills, MCP configs, or commands are needed
-> 2. **Do not silently create custom scripts.** Do not generate Python code, `setup.sh` files, or tarball uploads without user consent. But *do* proactively recommend the custom path (per rule 0) when the task is deterministic or high-frequency — surface the option and let the user choose.
-> 3. **If neither preset is the right fit**, do NOT silently fall back to custom automation. Instead, explain the available options to the user:
->    - **Prompt preset** — natural language prompt execution (LLM-driven)
->    - **Plugin preset** — load plugins with extended capabilities (skills, MCP, hooks, commands)
->    - **Custom script** — full control over code, with or without LLM; point them to `references/custom-automation.md`
->    - Let the user choose which approach to use.
-> 4. **Only create custom scripts after the user agrees to that path.** Refer to `references/custom-automation.md` for the full reference.
-> 5. **Before suggesting event-triggered (webhook) automations, check whether the deployment is publicly reachable.** Check `RUNTIME_URL`. Webhooks require an internet-accessible URL so that external services (GitHub, Slack, Linear, etc.) can deliver events to the automation service. If `RUNTIME_URL` is unset, empty, or resolves to a local or private address (`localhost`, `127.0.0.1`, `0.0.0.0`, or any RFC 1918 range: `10.x.x.x`, `192.168.x.x`, `172.16–31.x.x`), the service cannot receive inbound webhook traffic from the public internet. In that case:
+> 2. **Present the options, then build the one the user picks.** Whenever rule 0 applies, or neither preset is a clean fit (custom Python dependencies, a non-Python entrypoint, a multi-file project, direct SDK lifecycle control), lay the choices out side by side with a one-line note on cost and reliability for each, and let the user choose:
+>    - **Prompt preset** - natural language prompt execution (LLM-driven)
+>    - **Plugin preset** - load plugins with extended capabilities (skills, MCP, hooks, commands)
+>    - **Custom script** - full control over code, with or without an LLM; see `references/custom-automation.md`
+>
+>    Do not silently fall back to either side. The "ready to deploy?" confirmation in the creation process applies to every path equally; a custom script needs no extra permission beyond it, and a preset gets no pass on it.
+> 3. **Building a custom script:** follow `references/custom-automation.md` for tarball packaging, validation, and upload. The *Custom Script Example (No LLM)* below shows the whole flow end to end.
+> 4. **Before suggesting event-triggered (webhook) automations, check whether the deployment is publicly reachable.** Check `RUNTIME_URL`. Webhooks require an internet-accessible URL so that external services (GitHub, Slack, Linear, etc.) can deliver events to the automation service. If `RUNTIME_URL` is unset, empty, or resolves to a local or private address (`localhost`, `127.0.0.1`, `0.0.0.0`, or any RFC 1918 range: `10.x.x.x`, `192.168.x.x`, `172.16–31.x.x`), the service cannot receive inbound webhook traffic from the public internet. In that case:
 >    - **Recommend a cron-based polling automation instead.** Have the automation run on a schedule and call the external service's API (e.g., the GitHub REST API) to check for new events since the last run.
 >    - Explain the limitation clearly to the user: "Because this is a local deployment, external services can't reach the webhook endpoint. I'll set up a polling automation using a cron schedule instead."
 
@@ -255,8 +255,10 @@ curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
 Write the prompt as an instruction to an AI agent. The prompt executes inside a sandbox with full tool access (bash, file editing, etc.), the user's configured LLM, stored secrets, and MCP server integrations. Examples:
 
 - `"Generate a weekly status report summarizing the team's GitHub activity and post it to Slack"`
-- `"Check the production API health endpoint every hour and alert if it returns non-200"`
-- `"Pull the latest data from our analytics API and update the dashboard spreadsheet"`
+- `"Read yesterday's new error reports in Sentry, group them by likely root cause, and open one GitHub issue per new failure pattern with a proposed fix"`
+- `"Go through support tickets tagged 'bug' since the last run, try to reproduce each against main, and comment on the ticket with what you found"`
+
+Each of these needs judgment: deciding what counts as a pattern, whether a reproduction succeeded, what is worth reporting. A task whose output could be written as a fixed template right now belongs in a custom script instead (see *Custom Script Example (No LLM)* below).
 
 #### Cron Schedule
 
@@ -296,24 +298,105 @@ curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
   }'
 ```
 
-**Weekly cleanup:**
+**Weekly dependency review:**
 ```bash
 curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
   -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
   -H "Content-Type: application/json" \
   -d '{
-    "name": "Weekly Cleanup",
-    "prompt": "Clean up temporary files older than 7 days and send a summary of what was removed",
+    "name": "Weekly Dependency Review",
+    "prompt": "Check the repository dependencies for new releases. Read each changelog, open one PR with the upgrades that look safe, and list any release with breaking changes in the PR description so a human can decide on it",
     "trigger": {"type": "cron", "schedule": "0 2 * * 0", "timezone": "UTC"},
-    "timeout": 300
+    "timeout": 1800
   }'
 ```
 
+### Custom Script Example (No LLM)
+
+The same shape as the prompt preset, for a task that needs no reasoning: check a URL on a schedule and post to Slack only when it fails. Every run takes a moment and costs no tokens. This is the complete flow; `get_secret` and `fire_callback` are the helpers from *No-LLM Script Helpers* above.
+
+```bash
+mkdir healthcheck && cd healthcheck
+
+cat > main.py << 'PYEOF'
+"""Hourly health check: alert Slack on a non-200 response. No LLM, no SDK."""
+import json, os, sys, urllib.request
+
+URL = "https://api.example.com/health"
+CHANNEL = "C12345678"
+
+def get_secret(name):
+    url = os.environ.get("AGENT_SERVER_URL", "").rstrip("/")
+    key = os.environ.get("SESSION_API_KEY") or os.environ.get("OH_SESSION_API_KEYS_0", "")
+    if url:  # local Agent Canvas
+        url = f"{url}/api/settings/secrets/{name}"
+    else:  # OpenHands Cloud / Enterprise
+        api = os.environ["OPENHANDS_CLOUD_API_URL"].rstrip("/")
+        url = f"{api}/api/v1/sandboxes/{os.environ['SANDBOX_ID']}/settings/secrets/{name}"
+    req = urllib.request.Request(url,
+        headers={"X-Session-API-Key": key})
+    with urllib.request.urlopen(req) as r:
+        return r.read().decode().strip()
+
+def fire_callback(status="COMPLETED", error=None):
+    url = os.environ.get("AUTOMATION_CALLBACK_URL", "")
+    if not url: return
+    body = {"status": status, "run_id": os.environ.get("AUTOMATION_RUN_ID", "")}
+    if error: body["error"] = error
+    req = urllib.request.Request(url, data=json.dumps(body).encode(), headers={
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {os.environ.get('AUTOMATION_CALLBACK_API_KEY', '')}",
+    })
+    try: urllib.request.urlopen(req)
+    except Exception as e: print(f"Callback error: {e}")
+
+def slack(text):
+    token = get_secret("SLACK_BOT_TOKEN")
+    req = urllib.request.Request("https://slack.com/api/chat.postMessage",
+        data=json.dumps({"channel": CHANNEL, "text": text}).encode(),
+        headers={"Content-Type": "application/json", "Authorization": f"Bearer {token}"})
+    urllib.request.urlopen(req)
+
+try:
+    try:
+        status = urllib.request.urlopen(URL, timeout=10).status
+    except Exception as e:
+        status = f"error: {e}"
+    if status != 200:
+        slack(f":rotating_light: {URL} returned {status}")
+    print(f"{URL} -> {status}")
+    fire_callback("COMPLETED")
+except Exception as e:
+    print(f"ERROR: {e}", file=sys.stderr)
+    fire_callback("FAILED", str(e))
+    sys.exit(1)
+PYEOF
+
+tar -czf ../healthcheck.tar.gz .
+
+TARBALL_PATH=$(curl -s -X POST "${OPENHANDS_HOST}/api/automation/v1/uploads?name=healthcheck" \
+  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
+  -H "Content-Type: application/gzip" \
+  --data-binary @../healthcheck.tar.gz | jq -r '.tarball_path')
+
+curl -X POST "${OPENHANDS_HOST}/api/automation/v1" \
+  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"name\": \"Hourly Health Check\",
+    \"trigger\": {\"type\": \"cron\", \"schedule\": \"0 * * * *\", \"timezone\": \"UTC\"},
+    \"tarball_path\": \"$TARBALL_PATH\",
+    \"entrypoint\": \"python3 main.py\"
+  }"
+```
+
+For state between runs (last alert time, last seen event), use the KV store helpers in `references/custom-automation.md#state-persistence-kv-store`.
+
 ---
 
 ## Polling as a Webhook Alternative
 
-When the deployment cannot receive inbound webhook traffic (see rule 5), use a cron-triggered automation that calls the external service’s API on a schedule to check for new events.
+When the deployment cannot receive inbound webhook traffic (see rule 4), use a cron-triggered automation that calls the external service’s API on a schedule to check for new events.
 
 ### Polling vs. Webhooks at a Glance
 
@@ -442,15 +525,15 @@ curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
   }'
 ```
 
-#### GitHub: Run tests on push to main
+#### GitHub: Flag risky changes pushed to main
 
 ```bash
 curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
   -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
   -H "Content-Type: application/json" \
   -d '{
-    "name": "Run Tests on Main",
-    "prompt": "Clone the repository and run the test suite. Report any failures.",
+    "name": "Risky Change Watch",
+    "prompt": "Review the diff of this push. If it touches authentication, billing, data migrations, or anything that changes behavior for existing users, open an issue that explains the risk in plain terms and mentions the code owners. Otherwise do nothing.",
     "trigger": {
       "type": "event",
       "source": "github",
@@ -942,7 +1025,7 @@ The **prompt preset** is the right default for genuinely agent-shaped work — a
 
 **Watch for deterministic, high-frequency patterns.** Requests like "send a daily standup reminder", "ping a healthcheck URL every minute", "post a random quote every 5 minutes", or "rotate a fact-of-the-day message" do not need an LLM. Surface this to the user explicitly with a rough cost framing (e.g. "this schedule will invoke your LLM ~288 times/day") before defaulting to a preset. As a rule of thumb, any cron tighter than hourly deserves a deliberate "should this really be agent-driven?" check.
 
-**When neither preset is the right fit** (deterministic task, custom Python dependencies, non-Python entrypoint, multi-file project structure, direct SDK lifecycle control), explain the options to the user and let them decide. Do not attempt custom automation without explicit user agreement. If they choose the custom route, refer to `references/custom-automation.md`.
+**When neither preset is the right fit** (deterministic task, custom Python dependencies, non-Python entrypoint, multi-file project structure, direct SDK lifecycle control), explain the options and let the user decide, exactly as for any other automation. If they choose the custom route, follow `references/custom-automation.md` and the *Custom Script Example (No LLM)* above.
 
 ## Security Considerations
 
@@ -955,7 +1038,6 @@ See `references/security.md` — also covers narrowing triggers and sender-level
 
 ## Reference Files
 
-- **`references/custom-automation.md`** — Detailed guide for custom automations: tarball uploads, code structure (SDK and no-LLM), state persistence via the KV store, environment variables, validation rules, and complete examples. Consult this whenever you need to evaluate or recommend the custom path (including for deterministic / cost-sensitive tasks per rule 0). Only *implement* a custom automation after the user agrees to that path.
+- **`references/custom-automation.md`** — Detailed guide for custom automations: tarball uploads, code structure (SDK and no-LLM), state persistence via the KV store, environment variables, validation rules, and complete examples. Consult this whenever you need to evaluate, recommend, or build the custom path (including for deterministic / cost-sensitive tasks per rule 0).
 - **`references/ab-testing.md`** — A/B testing for plugin automations: defining variants with weights, experiment configuration, variant selection logic, observability via conversation tags, and complete examples. Consult this when a user wants to compare plugin versions or configurations.
-- **`references/security.md`** — Trust boundaries: untrusted content vs. verified sender, least-privilege secrets, trigger scoping, sender authorization, pre-deploy verification. Consult whenever an automation handles external input or forwards secrets to a spawned conversation.
 - **`references/security.md`** — Trust boundaries for automations: untrusted event content vs. verified sender, least-privilege secret scoping for spawned conversations, narrowing triggers, sender-level authorization, and verifying a script actually runs before deploying it. Consult this whenever an automation handles external/untrusted input (GitHub issues/PRs, Slack messages, any public-facing webhook) or forwards secrets to a spawned conversation.

package/skills/openhands-automation/references/custom-automation.md

@@ -1,13 +1,12 @@
 # Custom Automation Reference
 
-> **⚠️ Do NOT use this reference unless the user has explicitly requested a custom automation.** Always use the preset/prompt endpoint from the main SKILL.md first. If the preset approach cannot satisfy the requirement, explain the options to the user and let them decide.
-
 This file contains detailed documentation for creating custom automations with user-provided code, uploads, and entrypoints.
 
-**When to use custom automation (only if the user explicitly chooses this):**
+**When to use a custom automation:**
+- The task is deterministic and needs no LLM (fixed data, scheduled HTTP calls, templated messages), especially on a frequent schedule
 - Full control over the automation code structure is needed
 - Custom dependencies or a specific runtime are required
-- The user has confirmed that the prompt preset does not meet their requirements
+- The user picked this path after seeing the options side by side (see the agent behavior rules in `SKILL.md`)
 
 ## Table of Contents
 
@@ -250,6 +249,7 @@ uv pip install -q openhands-sdk openhands-workspace openhands-tools
 import os
 
 from openhands.sdk import Conversation
+from openhands.sdk.automation import automation_conversation_kwargs
 from openhands.tools.preset.default import get_default_agent
 from openhands.workspace import OpenHandsCloudWorkspace
 
@@ -267,13 +267,48 @@ with OpenHandsCloudWorkspace(
 ) as workspace:
     llm = workspace.get_llm()
     agent = get_default_agent(llm=llm, cli_mode=True)
-    conversation = Conversation(agent=agent, workspace=workspace)
+    conversation = Conversation(
+        agent=agent,
+        workspace=workspace,
+        **automation_conversation_kwargs(),
+    )
     conversation.send_message("Your automation prompt here")
     conversation.run()
     conversation.close()
 # OpenHandsCloudWorkspace.__exit__ fires the completion callback here.
 ```
 
+### Link automation conversations to run telemetry
+
+When an automation script starts a conversation, preserve the trace context that the automation service injected into the run. This links the conversation span to the triggering webhook, scheduler dispatch, and run record.
+
+- SDK conversations: pass `**automation_conversation_kwargs()` into every `Conversation(...)` call.
+- Direct agent-server API calls: merge `automation_observability_headers()` into the headers for each `POST /api/conversations` request.
+- If you add your own conversation tags, pass them through `conversation_tags={...}` instead of replacing the helper output.
+
+```python
+from openhands.sdk import Conversation
+from openhands.sdk.automation import (
+    automation_conversation_kwargs,
+    automation_observability_headers,
+)
+
+conversation = Conversation(
+    agent=agent,
+    workspace=workspace,
+    **automation_conversation_kwargs(),
+)
+
+headers = {
+    "X-Session-API-Key": api_key,
+    **automation_observability_headers(span_name="automation.conversation"),
+}
+# Use these headers when creating a backend conversation directly.
+# httpx.post(f"{agent_url}/api/conversations", headers=headers, json=payload)
+```
+
+The built-in prompt and plugin presets use this helper. Custom scripts should do the same for every new conversation so traces, observability metadata, and automation conversation tags stay attached.
+
 ### Selecting an LLM profile
 
 The automation service injects an `AUTOMATION_MODEL` environment variable holding the **LLM profile name** the automation should run with. This is the profile a user selects when editing the automation, or — when none is selected — a snapshot of the user's active profile taken when the automation was created. To honor it on every run, read `AUTOMATION_MODEL` and pass it to `workspace.get_llm(profile_name=...)`:
@@ -300,13 +335,27 @@ Conversations started during a run remain accessible in the OpenHands UI after t
 
 ```python
 # Default: conversation persists after close (users can view/continue it)
-conversation = Conversation(agent=agent, workspace=workspace)
+conversation = Conversation(
+    agent=agent,
+    workspace=workspace,
+    **automation_conversation_kwargs(),
+)
 
 # Explicitly persist (same as default)
-conversation = Conversation(agent=agent, workspace=workspace, delete_on_close=False)
+conversation = Conversation(
+    agent=agent,
+    workspace=workspace,
+    delete_on_close=False,
+    **automation_conversation_kwargs(),
+)
 
 # Delete conversation resources on close
-conversation = Conversation(agent=agent, workspace=workspace, delete_on_close=True)
+conversation = Conversation(
+    agent=agent,
+    workspace=workspace,
+    delete_on_close=True,
+    **automation_conversation_kwargs(),
+)
 ```
 
 The agent server itself persists until it times out or is manually deleted; this is managed by the automation service, not by the workspace.
@@ -340,7 +389,11 @@ else:
     with OpenHandsCloudWorkspace(local_agent_server_mode=True, cloud_api_url=api_url, cloud_api_key=api_key) as workspace:
         llm = workspace.get_llm()
         agent = get_default_agent(llm=llm, cli_mode=True)
-        conversation = Conversation(agent=agent, workspace=workspace)
+        conversation = Conversation(
+            agent=agent,
+            workspace=workspace,
+            **automation_conversation_kwargs(),
+        )
         conversation.send_message(f"Investigate these alerts and open GitHub issues: {alerts}")
         conversation.run()
         conversation.close()
@@ -359,7 +412,11 @@ from openhands.sdk.conversation.state import ConversationExecutionStatus
 with OpenHandsCloudWorkspace(local_agent_server_mode=True, cloud_api_url=api_url, cloud_api_key=api_key) as workspace:
     llm = workspace.get_llm()
     agent = get_default_agent(llm=llm, cli_mode=True)
-    conversation = Conversation(agent=agent, workspace=workspace)
+    conversation = Conversation(
+        agent=agent,
+        workspace=workspace,
+        **automation_conversation_kwargs(),
+    )
     conversation.send_message("Run a long analysis task")
     # Conversation is now running asynchronously in the agent server.
 
@@ -405,7 +462,12 @@ stop_hook = HookConfig(
 with OpenHandsCloudWorkspace(local_agent_server_mode=True, cloud_api_url=api_url, cloud_api_key=api_key) as workspace:
     llm = workspace.get_llm()
     agent = get_default_agent(llm=llm, cli_mode=True)
-    conversation = Conversation(agent=agent, workspace=workspace, hook_config=stop_hook)
+    conversation = Conversation(
+        agent=agent,
+        workspace=workspace,
+        hook_config=stop_hook,
+        **automation_conversation_kwargs(),
+    )
     conversation.send_message("Do some long-running work")
     # Don't call run() — the conversation runs asynchronously.
     # When the agent stops, the stop hook will fire the callback.
@@ -766,6 +828,7 @@ import os
 import json
 
 from openhands.sdk import Conversation
+from openhands.sdk.automation import automation_conversation_kwargs
 from openhands.tools.preset.default import get_default_agent
 from openhands.workspace import OpenHandsCloudWorkspace
 
@@ -782,7 +845,11 @@ with OpenHandsCloudWorkspace(
 ) as workspace:
     llm = workspace.get_llm()
     agent = get_default_agent(llm=llm, cli_mode=True)
-    conversation = Conversation(agent=agent, workspace=workspace)
+    conversation = Conversation(
+        agent=agent,
+        workspace=workspace,
+        **automation_conversation_kwargs(),
+    )
     conversation.send_message("Generate a weekly status report")
     conversation.run()
     conversation.close()

package/skills/openhands-sdk/SKILL.md

@@ -131,10 +131,11 @@ print("All done!")
 - [Secret Registry](https://docs.openhands.dev/sdk/guides/secrets.md): Provide environment variables and secrets to agent workspace securely.
 - [Security & Action Confirmation](https://docs.openhands.dev/sdk/guides/security.md): Control agent action execution through confirmation policy and security analyzer.
 - [Send Message While Running](https://docs.openhands.dev/sdk/guides/convo-send-message-while-running.md): Interrupt running agents to provide additional context or corrections.
-- [Software Agent SDK](https://docs.openhands.dev/sdk.md): Build AI agents that write software. A clean, modular SDK with production-ready tools.
+- [Software Agent SDK](https://docs.openhands.dev/sdk/index.md): Build AI agents that write software. A clean, modular SDK with production-ready tools.
 - [Structured Output](https://docs.openhands.dev/sdk/guides/structured-output.md): Attach a schema to any tool so the LLM returns typed, validated fields alongside the tool's own arguments.
 - [Stuck Detector](https://docs.openhands.dev/sdk/guides/agent-stuck-detector.md): Detect and handle stuck agents automatically with timeout mechanisms.
 - [Task Tool Set](https://docs.openhands.dev/sdk/guides/task-tool-set.md): Delegate complex work to specialized sub-agents that run synchronously and return results to the parent agent.
+- [Task-Based Model Routing](https://docs.openhands.dev/sdk/guides/llm-task-routing.md): Let the agent pick the best saved LLM profile for the task at hand with the built-in route_task_to_model tool.
 - [Theory of Mind (TOM) Agent](https://docs.openhands.dev/sdk/guides/agent-tom-agent.md): Enable your agent to understand user intent and preferences through Theory of Mind capabilities, providing personalized guidance based on user modeling.
 - [TODO Management](https://docs.openhands.dev/sdk/guides/github-workflows/todo-management.md): Implement TODOs using OpenHands Agent
 

package/skills/qa-changes/README.md

@@ -14,5 +14,7 @@ The skill guides the agent through four phases:
 
 1. **Understand** — Classify changes and identify entry points
 2. **Setup** — Install dependencies, build, check CI status
-3. **Exercise** — Run the actual code as a user would (browser, CLI, API requests)
+3. **Exercise** — Run the actual code as a user would (browser, CLI, API requests).
+   For frontend changes, capture screenshots of each affected state and a GIF of
+   the key interaction (before/after where behavior changes)
 4. **Report** — Post a structured QA report with evidence and a verdict

package/skills/qa-changes/SKILL.md

@@ -75,6 +75,37 @@ This is the most important phase. **Actually use the software** the way a real u
 - Verify the visual change renders correctly. Take screenshots as evidence.
 - Test user interactions (clicks, form submissions, navigation).
 - Try at least one edge case (empty state, long text, missing data).
+- Then capture visual evidence and attach it to the PR (see next step).
+
+**Capture visual evidence (frontend PRs only):**
+
+If the PR has frontend work, run the affected screens from the branch's final
+state and record what a reviewer would otherwise have to imagine from the diff.
+The goal: the change can be reviewed **by observation, not by reading code.**
+
+1. **Screenshot each relevant state** of every affected screen - whichever
+   apply: *empty*, *loading*, *error*, and *populated*. Skip states the screen
+   genuinely cannot reach.
+2. **Record the key interaction end to end** - the main flow the PR changes,
+   driven the way a user would. Prefer a GIF: GitHub renders a GIF inline from
+   an image link, but only links a video file.
+3. **Where behavior changes, capture before/after** - the same state or
+   interaction on the base branch and on the PR branch, so the delta is
+   visible.
+4. **Attach it to the report.** Embed the images and GIF in the QA report so
+   they render inline, and label each one (screen and state, or before/after).
+   Do not push commits to the PR branch to host media: that changes the head
+   you are verifying, and the shipped QA workflow has read-only access to
+   repository contents. If you cannot upload media where the report is posted,
+   save the files where the run keeps its artifacts, say where to find them,
+   and describe in text what each capture shows. In the `qa-changes` GitHub
+   Action that is `$GITHUB_WORKSPACE/output/`, the parent of the PR checkout
+   you work in, which the action uploads as the `openhands-qa-changes-logs`
+   artifact; a relative `output/` inside the checkout is not uploaded.
+
+Keep it proportional: capture the screens the PR actually touches, not the whole
+app. If you cannot render a screen (missing data, an unreachable state, no
+browser), say so in the report rather than faking it.
 
 **For CLI changes:**
 - Run the CLI command with realistic arguments. Capture stdout and stderr.
@@ -181,6 +212,16 @@ prior state rather than reproducing a failure.}
 
 </details>
 
+<details><summary>Visual Evidence</summary>
+
+{Frontend PRs only. Embed the screenshots (per screen and state: empty,
+loading, error, populated) and the GIF of the key interaction so they
+render inline, or say where the captures are stored if they could not be
+uploaded. Where behavior changed, show before/after. Label each clearly.
+Omit this section entirely for non-frontend PRs.}
+
+</details>
+
 <details><summary>Unable to Verify</summary>
 
 {What could not be verified, what was attempted, and suggested
@@ -221,6 +262,7 @@ was verified.}
 - **Run the code, not the tests.** Execute the actual software — start servers, run CLI commands, make HTTP requests, open browsers. Do not run `pytest`, `npm test`, or equivalent test suites. That is CI's job.
 - **Do not analyze code.** Reading files and commenting on style, structure, or logic is code review's job. Your job is to exercise behavior, not read source files.
 - **Set a high bar.** If the change affects a UI, open it in a real browser. If it affects a CLI, run the actual CLI with real inputs. If it affects an API, make real HTTP requests.
+- **Make frontend changes reviewable by observation.** For UI PRs, attach screenshots of each relevant state and a GIF of the key interaction (before/after where behavior changes) so a reviewer can see the change, not infer it from the diff.
 - **Test what the PR claims.** The PR description is the specification. Verify the claim, not hypothetical scenarios.
 - **Leave CI to CI.** Do not re-run tests, linters, formatters, or type checkers. Note CI status, then focus entirely on functional verification that CI cannot do.
 - **Report evidence, not opinions.** Include exact commands, outputs, and error messages — inside collapsible blocks.

package/skills/simplified-technical-english/.claude-plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "simplified-technical-english",
+  "version": "1.0.0",
+  "description": "Write explanations and chat in the style of ASD-STE100 Simplified Technical English: short active sentences, one idea each, plain consistent words. Applies to prose only, never to code.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "simplified-technical-english"
+  ]
+}

package/skills/simplified-technical-english/.codex-plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "simplified-technical-english",
+  "version": "1.0.0",
+  "description": "Write explanations and chat in the style of ASD-STE100 Simplified Technical English: short active sentences, one idea each, plain consistent words. Applies to prose only, never to code.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "simplified-technical-english"
+  ]
+}

package/skills/simplified-technical-english/.plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "simplified-technical-english",
+  "version": "1.0.0",
+  "description": "Write explanations and chat in the style of ASD-STE100 Simplified Technical English: short active sentences, one idea each, plain consistent words. Applies to prose only, never to code.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "simplified-technical-english"
+  ]
+}

package/skills/simplified-technical-english/README.md

@@ -0,0 +1,21 @@
+# Simplified Technical English skill
+
+This skill helps OpenHands write **prose** in the style of ASD-STE100 Simplified
+Technical English: short active sentences, one idea each, plain and consistent
+words. The aim is text that is easy to read the first time. This matters most
+for readers whose first language is not English, and for instructions where a
+misread is costly.
+
+Use it for:
+
+- chat replies, explanations, summaries, and step lists that need maximum clarity
+- ops, deploy, or security instructions where a misread is costly
+- briefing another agent to produce plain, scannable prose
+
+**The hard boundary is prose only.** The skill must never change code, identifiers,
+CLI flags, API fields, commit messages, or reference/API docs. A controlled
+English vocabulary must not bleed into code, where exact domain terms win.
+
+It complements `plain-english-content` (GOV.UK-style content design) and
+`technical-writing` (conversational engineering prose); this one adds the
+ASD-STE100 register and the explicit "do not touch code" guardrail.