npm - @openhands/agent-canvas - Versions diffs - 1.18.0 → 1.20.0 - Mend

@openhands/agent-canvas 1.18.0 → 1.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (420) hide show

package/build/assets/{vendor~root~root-layout~index-home~home~conversation-panel~conversation~launch~skills-setti~jz4f6vo2-C7HiY4Ae.js → vendor~root~root-layout~index-home~home~conversation-panel~conversation~launch~skills-setti~jz4f6vo2-BqdU447s.js} RENAMED Viewed

@@ -1437,6 +1437,10 @@ reviewing it would tell you nothing the first did not.
 ---
+The script imports shared GitHub transport from
+\`scripts/github_client.py\`, installed with this skill. Include it beside
+\`main.py\` when packaging manually, as shown below.
 ## Prerequisites
 ### Required secret
@@ -1560,9 +1564,11 @@ substitutions near the top of the file:
 Use a safe string writer such as \`json.dumps(value)\` when inserting user-provided
 repository names or prefixes into Python string literals.
-Write the customized script to a temporary build directory and validate it:
+Run these commands from this skill's directory, write the customized script
+to a temporary build directory, and validate it:
 \`\`\`bash
 mkdir -p /tmp/agents-md-build
+cp -L scripts/github_client.py /tmp/agents-md-build/github_client.py
 # write the customized main.py to /tmp/agents-md-build/main.py
 python3 -m py_compile /tmp/agents-md-build/main.py && echo "Syntax OK"
 \`\`\`
@@ -1676,7 +1682,14 @@ For each repository:
 | \`git is not available in the automation runtime\` | The runtime image has no git | Use a runtime image that ships git |
 | Pull request says nothing changed | The agent judged AGENTS.md accurate but still committed | Read its summary in the pull request body; tighten the prompt if it keeps making cosmetic edits |
 | Every run reports \`no-changes\` | AGENTS.md is accurate, or the agent cannot read the repository | Open the conversation from the run log and check what it saw |
-| Clones remain under \`agents-md/\` | Their conversations had not stopped yet | They are removed by a later run once the conversation is terminal |`,category:`automations`},{name:`github-issue-to-pr`,description:`Create an automation that implements GitHub issues when a configurable trigger label is applied. Polls one or more repositories deterministically, clones the default branch, starts one OpenHands conversation per label event, then commits, pushes, and opens the pull request itself.`,triggers:[`/issue-to-pr:setup`],content:`# GitHub Issue to PR Automation
+| Clones remain under \`agents-md/\` | Their conversations had not stopped yet | They are removed by a later run once the conversation is terminal |`,category:`automations`},{name:`github-delivery-watchdog`,description:`Periodically check pull requests and merge only current heads with independent review, tests, and passing CI.`,triggers:[`/github-delivery-watchdog`],content:"# GitHub delivery watchdog\n\nThis is a deterministic scheduled host command. It creates no agent or\nconversation and needs no agent profile. Configure a repository-scoped\nfine-grained PAT with Contents and Issues read/write plus Pull requests, Actions,\nCommit statuses, and Metadata read. Contents write permits merge; Issues write\nretains the review label when the branch is updated. Never put the token value in\nthe automation definition.\n\nPackage `scripts/worker.py` as `worker.py` and the shared\n`scripts/github_client.py` as `github_client.py`.\nThe catalog bundle declares these exact files. Its `config.json` supplies\n`repos`, `branch_prefix`, and the saved secret name. The shared GitHub client\nresolves only that named secret. Automation owns scheduling and cancellation.\n\nSet `branch_prefix` (default `openhands/issue`), `base_branch` (defaults to the repository's default branch),\nand `required_workflow_ids` when particular Actions workflows must run. The\nwatchdog requires `software-factory/tests` and `software-factory/review` success\nstatuses on the exact head, all other statuses and Actions passing, a current\nbase, a non-draft PR, and GitHub reporting it mergeable. Missing, pending, failed,\nor inaccessible evidence does not permit merge. A changed head requires fresh\nreview and tests. When an accepted branch is behind the base, the watchdog asks\nGitHub to update it and retains the review trigger label; it considers the new\nhead only on a later run. The merge request includes the expected head SHA.\n\nActions are optional when `required_workflow_ids` is empty; the two acceptance\nstatuses remain mandatory. Configure workflow IDs when GitHub Actions must also\nsupply evidence. Branch protection remains GitHub's final merge gate.",category:`automations`},{name:`github-issue-to-pr`,description:`Create an automation that implements GitHub issues when a configurable trigger label is applied. Polls one or more repositories deterministically, clones the default branch, starts one OpenHands conversation per label event, then commits, pushes, and opens the pull request itself.`,triggers:[`/issue-to-pr:setup`],content:`# GitHub Issue to PR Automation
+## Agent Canvas catalog
+For new Agent Canvas installations, use the **GitHub issue to PR** catalog
+entry. Its deterministic \`worker.py\` scanner delegates each eligible issue to a
+stable conversation using the selected agent profile. The manual upload flow
+below remains for existing deployments and is deprecated for new installations.
 Create a cron automation that watches one or more GitHub repositories for issues
 with a trigger label, starts an OpenHands conversation once per label event with
@@ -1707,6 +1720,11 @@ environment of a command that mentions it, and masks it in the output.
 ---
+The script imports shared GitHub transport from
+\`scripts/github_client.py\`, installed with this skill. Include it beside
+\`main.py\` when packaging manually, as shown below; catalog bundles include it
+automatically.
 ## Prerequisites
 ### Required secret
@@ -1872,9 +1890,11 @@ Use a safe string writer such as \`json.dumps(value)\` when inserting user-provi
 repository names, labels, or prefixes into Python string literals.
 \`json.dumps(list_of_repos)\` produces the whole \`REPOS\` list safely in one step.
-Write the customized script to a temporary build directory:
+Run these commands from this skill's directory and write the customized script
+to a temporary build directory:
 \`\`\`bash
 mkdir -p /tmp/issue-to-pr-build
+cp -L scripts/github_client.py /tmp/issue-to-pr-build/github_client.py
 # write the customized main.py to /tmp/issue-to-pr-build/main.py
 \`\`\`
@@ -2037,7 +2057,33 @@ The completion callback fires once for the whole run.
 | Same issue not picked up again after new comments | Its label event was already processed | Remove and re-apply the trigger label |
 | Agent reports it cannot push or open a PR | By design - it has no credentials | No action; the automation pushes and opens the pull request after the agent stops |
 | A backlog of labelled issues starts slowly | \`MAX_NEW_PER_RUN\` caps how many conversations one poll starts | Wait for the next polls, or raise the cap in the script |
-| Clones remain under \`issue-to-pr/\` | Their conversations had not stopped yet | They are removed by a later poll once the conversation is terminal |`,category:`automations`},{name:`github-pr-review`,description:`Post PR review comments using the GitHub API with inline comments, suggestions, and priority labels.`,triggers:[`/github-pr-review`],content:`# GitHub PR Review
+| Clones remain under \`issue-to-pr/\` | Their conversations had not stopped yet | They are removed by a later poll once the conversation is terminal |`,category:`automations`},{name:`github-issue-triage`,description:`Prioritize open issues and establish acceptance criteria before marking them ready for development.`,triggers:[`/github-issue-triage`],content:`# GitHub issue triage
+Prioritize open issues and establish acceptance criteria before marking them ready for development.
+Create this automation separately from implementation and review. Use a
+fine-grained GitHub PAT limited to the selected repositories with Issues: read and
+write. Never put the token value in the automation definition or prompt.
+Package \`worker.py\` with the shared \`github_client.py\` and
+\`agent_conversation.py\` helpers. Supply \`config.json\` with \`repos\` and the saved
+GitHub secret name; the entrypoint is \`python3 worker.py\`. Include that secret in
+the selected profile so the delegated agent can use GitHub. Naming it in the
+automation does not grant it to the agent.
+The scanner is an ordinary Automation host command. It submits selected issues
+through the shared KV-backed conversation dispatcher, which creates or resumes
+one stable conversation per issue through the Software Agent SDK. Only that
+agent workspace is local or Docker. Automation owns scheduling, cancellation,
+and cleanup.
+Honor \`Depends on: #12, #13\` lines. A dependency must be closed as completed.
+Post readable acceptance criteria and rationale. Add \`ready-for-dev\` only when
+criteria are actionable; preserve existing issue labels. Unclear issues stay open
+for clarification. Do not implement code or accept pull requests.
+Each scheduled run submits every changed eligible issue. A failure on one issue is
+reported and does not prevent the remaining issues from being submitted.`,category:`automations`},{name:`github-pr-review`,description:`Post PR review comments using the GitHub API with inline comments, suggestions, and priority labels.`,triggers:[`/github-pr-review`],content:`# GitHub PR Review
 Post structured code review feedback using the GitHub API with inline comments on specific lines.
 Windows PowerShell equivalents for JSON file creation, temp paths, line lookup, and fallback \`curl\` are in \`references/windows.md\`.
@@ -2218,6 +2264,13 @@ curl -X POST \\
 7. Keep the review body brief (details go in inline comments)
 8. If no issues: post a short approval message with no inline comments`,category:`code-hosting`},{name:`github-pr-reviewer`,description:`Create an automation that reviews GitHub pull requests when a configurable trigger label is applied. Polls one or more repositories deterministically, starts one OpenHands review conversation per label event with the pull request's head commit already checked out, and publishes the review to GitHub.`,triggers:[`/pr-reviewer:setup`],content:`# GitHub PR Reviewer Automation
+## Agent Canvas catalog
+For new Agent Canvas installations, use the **GitHub code review** catalog
+entry. Its deterministic \`worker.py\` scanner delegates each labeled exact head
+to a stable conversation using the selected agent profile. The manual upload
+flow below remains for existing deployments and is deprecated for new installations.
 Create a cron automation that watches one or more GitHub repositories for pull
 requests with a review trigger label, starts an OpenHands review conversation
 once per label event, and publishes the AI review to GitHub.
@@ -2236,6 +2289,11 @@ checkout once the conversation has stopped. Nothing accumulates between runs.
 ---
+The script imports shared GitHub transport from
+\`scripts/github_client.py\`, installed with this skill. Include it beside
+\`main.py\` when packaging manually, as shown below; catalog bundles include it
+automatically.
 ## Prerequisites
 ### Required secret
@@ -2368,9 +2426,11 @@ Use a safe string writer such as \`json.dumps(value)\` when inserting user-provi
 repository names, labels, or style instructions into Python string literals.
 \`json.dumps(list_of_repos)\` produces the whole \`REPOS\` list safely in one step.
-Write the customized script to a temporary build directory:
+Run these commands from this skill's directory and write the customized script
+to a temporary build directory:
 \`\`\`bash
 mkdir -p /tmp/pr-reviewer-build
+cp -L scripts/github_client.py /tmp/pr-reviewer-build/github_client.py
 # write the customized main.py to /tmp/pr-reviewer-build/main.py
 \`\`\`
@@ -2544,6 +2604,10 @@ On every subsequent run:
 ---
+The script imports shared GitHub transport from
+\`scripts/github_client.py\`, installed with this skill. Include it beside
+\`main.py\` when packaging manually, as shown below.
 ## Prerequisites
 ### Required secret
@@ -2688,9 +2752,11 @@ constant substitutions near the top of the file:
 | \`ALLOWED_GITHUB_LOGINS = ["<TOKEN_OWNER>"]\` | \`ALLOWED_GITHUB_LOGINS = {allowed_logins_list}\` |
 | \`DEFAULT_OPENHANDS_URL = "http://localhost:8000"\` | \`DEFAULT_OPENHANDS_URL = "{url}"\` (keep default if the user has no preference) |
-Write the customised script to a temporary build directory:
+Run these commands from this skill's directory and write the customised script
+to a temporary build directory:
 \`\`\`bash
 mkdir -p /tmp/github-monitor-build
+cp -L scripts/github_client.py /tmp/github-monitor-build/github_client.py
 # (write the customised main.py to /tmp/github-monitor-build/main.py)
 \`\`\`
@@ -2821,7 +2887,403 @@ Each cron run executes \`main.py\`, which:
 | Comments posted but no conversation created | Agent server URL wrong | Check \`OPENHANDS_URL\` secret and \`AGENT_SERVER_URL\` env var |
 | Same comment processed twice | \`processed_comment_ids\` cleared | State file was deleted; harmless but duplicate comment may appear |
 | Summary never posted | Conversation stuck in \`running\` | Open the conversation in the OpenHands UI; agent may need input |
-| No events detected after first run | \`last_poll\` in the future | Delete the state file to reset; it will be recreated on next run |`,category:`automations`},{name:`gitlab`,description:`Interact with GitLab repositories, merge requests, and APIs using the GITLAB_TOKEN environment variable. Use when working with code hosted on GitLab or managing GitLab resources.`,triggers:[`gitlab`],content:"You have access to an environment variable, `GITLAB_TOKEN`, which allows you to interact with\nthe GitLab API.\n\n<IMPORTANT>\nYou can use `curl` with the `GITLAB_TOKEN` to interact with GitLab's API.\nALWAYS use the GitLab API for operations instead of a web browser.\nALWAYS use the `create_mr` tool to open a merge request\n</IMPORTANT>\n\nIf you encounter authentication issues when pushing to GitLab (such as password prompts or permission errors), the old token may have expired. In such case, update the remote URL to include the current token: `git remote set-url origin https://oauth2:${GITLAB_TOKEN}@gitlab.com/username/repo.git`\n\nHere are some instructions for pushing, but ONLY do this if the user asks you to:\n* NEVER push directly to the `main` or `master` branch\n* Git config (username and email) is pre-set. Do not modify.\n* You may already be on a branch starting with `openhands-workspace`. Create a new branch with a better name before pushing.\n* Use the `create_mr` tool to create a merge request, if you haven't already\n* Once you've created your own branch or a merge request, continue to update it. Do NOT create a new one unless you are explicitly asked to. Update the PR title and description as necessary, but don't change the branch name.\n* Use the main branch as the base branch, unless the user requests otherwise\n* After opening or updating a merge request, send the user a short message with a link to the merge request.\n* Do all of the above in as few steps as possible. E.g. you could push changes with one step by running the following bash commands:\n```bash\ngit remote -v && git branch # to find the current org, repo and branch\ngit checkout -b create-widget && git add . && git commit -m \"Create widget\" && git push -u origin create-widget\n```\n\nOn Windows PowerShell, use `$env:GITLAB_TOKEN` in remote URLs and run the `git` commands as separate commands if `&&` is not supported by the installed shell.",category:`code-hosting`},{name:`incident-retrospective`,description:`Create an automation that drafts incident retrospectives. Gathers incident-channel messages from Slack, collects linked tickets and follow-ups from Linear, and publishes a retrospective draft to Notion with a timeline, impact summary, root-cause hypotheses, and action items.`,triggers:[`/incident-retro:setup`],content:`# Incident Retrospective Drafter Automation
+| No events detected after first run | \`last_poll\` in the future | Delete the state file to reset; it will be recreated on next run |`,category:`automations`},{name:`gitlab`,description:`Interact with GitLab repositories, merge requests, and APIs using the GITLAB_TOKEN environment variable. Use when working with code hosted on GitLab or managing GitLab resources.`,triggers:[`gitlab`],content:"You have access to an environment variable, `GITLAB_TOKEN`, which allows you to interact with\nthe GitLab API.\n\n<IMPORTANT>\nYou can use `curl` with the `GITLAB_TOKEN` to interact with GitLab's API.\nALWAYS use the GitLab API for operations instead of a web browser.\nALWAYS use the `create_mr` tool to open a merge request\n</IMPORTANT>\n\nIf you encounter authentication issues when pushing to GitLab (such as password prompts or permission errors), the old token may have expired. In such case, update the remote URL to include the current token: `git remote set-url origin https://oauth2:${GITLAB_TOKEN}@gitlab.com/username/repo.git`\n\nHere are some instructions for pushing, but ONLY do this if the user asks you to:\n* NEVER push directly to the `main` or `master` branch\n* Git config (username and email) is pre-set. Do not modify.\n* You may already be on a branch starting with `openhands-workspace`. Create a new branch with a better name before pushing.\n* Use the `create_mr` tool to create a merge request, if you haven't already\n* Once you've created your own branch or a merge request, continue to update it. Do NOT create a new one unless you are explicitly asked to. Update the PR title and description as necessary, but don't change the branch name.\n* Use the main branch as the base branch, unless the user requests otherwise\n* After opening or updating a merge request, send the user a short message with a link to the merge request.\n* Do all of the above in as few steps as possible. E.g. you could push changes with one step by running the following bash commands:\n```bash\ngit remote -v && git branch # to find the current org, repo and branch\ngit checkout -b create-widget && git add . && git commit -m \"Create widget\" && git push -u origin create-widget\n```\n\nOn Windows PowerShell, use `$env:GITLAB_TOKEN` in remote URLs and run the `git` commands as separate commands if `&&` is not supported by the installed shell.",category:`code-hosting`},{name:`gitlab-issue-to-mr`,description:`Create an automation that implements GitLab issues when a configurable trigger label is applied. Polls one or more projects deterministically, clones the default branch, starts one OpenHands conversation per label event, then commits, pushes, and opens the merge request itself.`,triggers:[`/issue-to-mr:setup`],content:`# GitLab Issue to MR Automation
+Create a cron automation that watches one or more GitLab projects for issues
+with a trigger label, starts an OpenHands conversation once per label event with
+the project's default branch already checked out, and opens a merge request with
+whatever the agent produced.
+The automation script is deterministic: issue discovery, label-event tracking,
+state persistence, the clone, the branch, the commit, the push, the merge
+request, the issue comments, and the clone's removal are all handled in Python.
+The LLM is invoked only to write the code.
+The agent is told **which** issue to implement, not what it says. It fetches the
+description, the discussion, and whatever they link to itself, so nothing in the
+prompt goes stale between dispatch and the moment the agent reads it.
+That needs read access, so the conversation is handed one secret, \`GITLAB_TOKEN\`.
+\`AGENT_SECRET_NAMES\` stays an allow-list: the rest of the deployment's secret
+store is not reachable from a conversation whose instructions came from an issue.
+The deployment's MCP servers are forwarded whole, matching \`github-pr-reviewer\`,
+so a connected GitLab server gives the agent typed tools rather than curl. What
+those servers reach is reachable from an issue-authored prompt, so connect only
+servers that may be driven by untrusted text.
+The agent also finishes the job: it commits, pushes its branch, and opens the
+merge request, so the merge request appears when the agent stops rather than on
+the next poll. The script does not trust that it happened - when the conversation
+ends it asks GitLab whether the merge request exists, and opens it itself when it
+does not. \`origin\` still carries no credential, so every GitLab command the agent
+runs has to name \`GITLAB_TOKEN\`; the SDK only puts a secret in the environment of
+a command that mentions it, and masks it in the output.
+---
+## Prerequisites
+### Required secret
+Verify that the following secret is set in **OpenHands Settings -> Secrets**:
+| Secret name | Token type | Minimum requirements |
+|---|---|---|
+| \`GITLAB_TOKEN\` | Personal access token | \`api\` scope, and at least the **Developer** role on every watched project |
+| \`GITLAB_TOKEN\` | Project or group access token | \`api\` scope, role **Developer** or above |
+The \`api\` scope is what GitLab grants read and write on issues, notes, branches,
+and merge requests through one scope; \`read_api\` polls happily and then fails at
+the point of pushing. Developer is the lowest role that can push a branch and
+open a merge request.
+Two things the role does not cover, and which fail the push rather than the poll:
+- **Protected branches.** The default branch is usually protected, but the
+  automation never pushes to it. Protect the branch prefix as well and the push
+  is rejected; leave \`openhands/issue-*\` unprotected.
+- **CI/CD files.** An issue asking for a pipeline change makes the agent touch
+  \`.gitlab-ci.yml\`. That needs no extra scope, but a project with a protected
+  CI/CD configuration path rejects the push.
+When several projects are monitored, the token must cover all of them.
+Check with:
+\`\`\`bash
+curl -s "https://gitlab.com/api/v4/user" \\
+  -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \\
+  | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('username') or d.get('message'))"
+\`\`\`
+If the token is missing or invalid, inform the user and stop.
+---
+## Setup Workflow
+Follow these steps in order.
+### Step 1 - Verify \`GITLAB_TOKEN\`
+Run the \`curl\` check above, against the user's instance if it is not
+\`gitlab.com\`.
+- If absent: *"GITLAB_TOKEN is not set. Please add it in OpenHands Settings ->
+  Secrets."* Stop.
+- If the API returns \`{"message": "401 Unauthorized"}\`: tell the user the token
+  is invalid and ask them to update it. Stop.
+### Step 2 - Collect the GitLab API URL
+Ask: *"Which GitLab instance? (Press Enter for gitlab.com. For a self-managed
+instance give its API root, e.g. \`https://gitlab.example.com/api/v4\`.)"*
+Record as \`GITLAB_API_URL\`. Default: \`https://gitlab.com/api/v4\`. Use this URL in
+every check below.
+### Step 3 - Collect projects
+Ask: *"Which GitLab projects should be watched?
+(Format: \`group/project\`, e.g. \`myorg/backend\`. Subgroups are fine -
+\`myorg/team/service\`. List several separated by commas to serve them all from one
+automation.)"*
+Validate access to **each** project, and confirm the token's role:
+\`\`\`bash
+PROJECT_ID=$(python3 -c "import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1], safe=''))" "{group}/{project}")
+curl -s "\${GITLAB_API_URL}/projects/\${PROJECT_ID}" \\
+  -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \\
+  | python3 -c "
+import json, sys
+d = json.load(sys.stdin)
+if 'message' in d or 'error' in d:
+    print('ERROR:', d.get('message') or d.get('error'))
+else:
+    perms = d.get('permissions') or {}
+    levels = [(perms.get(k) or {}).get('access_level') for k in ('project_access', 'group_access')]
+    levels = [n for n in levels if isinstance(n, int)]
+    role = max(levels) if levels else 'unknown'
+    print(f\\"Accessible. Default branch: {d.get('default_branch')}. Access level: {role}\\")
+"
+\`\`\`
+Record every accepted project into \`PROJECTS = ["{group}/{project}", ...]\`. If
+one project fails the check, say which and ask whether to continue without it.
+An access level below \`30\` (Developer) means the automation cannot open merge
+requests there; ask for a token with a higher role.
+Each project is polled independently and keeps its own state, so issue numbers
+never collide between them. The trigger label, branch prefix, and schedule are
+shared; a project needing different settings wants its own automation.
+### Step 4 - Collect trigger label
+Ask: *"Which issue label should trigger an implementation?
+(Press Enter for the default: \`openhands\`.)"*
+Record the answer as \`TRIGGER_LABEL\`. If the label does not exist yet, tell the
+user that GitLab will still record the event once the label is created and
+applied to an issue.
+The automation works an issue when it sees the latest matching label event for
+that label. To ask for another attempt later, remove and re-apply the label -
+that opens a second branch and a second merge request rather than overwriting the
+first.
+### Step 5 - Collect the merge request mode
+Ask: *"Should the merge requests be opened as drafts?
+  1. Draft (default) - title prefixed \`Draft:\`, ready for a human to mark ready
+  2. Ready for review - opened as a normal merge request
+(Press Enter for Draft)"*
+Map the choice to \`DRAFT_MERGE_REQUEST\` (\`True\` or \`False\`). GitLab has no draft
+flag on the merge request API; a draft is a title carrying the \`Draft: \` prefix,
+which the script adds.
+### Step 6 - Collect the branch prefix
+Ask: *"What branch prefix should the automation use?
+(Press Enter for the default: \`openhands/issue\`, which produces
+\`openhands/issue-42\`.)"*
+Record as \`BRANCH_PREFIX\`. Keep it free of spaces and of characters git rejects
+in a ref name, and make sure the prefix is not covered by a protected-branch
+rule.
+### Step 7 - Collect cron schedule
+Ask: *"How often should the automation poll for labelled issues?
+(Press Enter for the default: every 5 minutes.
+Use a cron expression for a different interval, e.g. \`0 * * * *\` = hourly)"*
+Default: \`*/5 * * * *\`.
+Record as \`CRON_SCHEDULE\`.
+### Step 8 - Confirm the secret scope
+The agent is handed \`GITLAB_TOKEN\`, because it reads the issue and its discussion
+itself. Ask: *"Beyond the GitLab token, does the project's build need a secret of
+its own - a package registry token, for example? (Press Enter for none.)"*
+Record the answers appended to the default, as
+\`AGENT_SECRET_NAMES = ["GITLAB_TOKEN", "NAME", ...]\`.
+Keep it an allow-list. Forwarding the whole secret store would put every
+credential in the deployment behind a prompt written by whoever opened the issue.
+If the projects are public and you would rather the conversation held no
+credential at all, set the list to \`[]\` - the agent can still read a public issue
+unauthenticated, and private projects then stop working.
+The deployment's MCP servers are a separate matter: they are forwarded whole, so
+the conversation can reach everything they expose. Say so, and check the user is
+willing to have those servers driven by text written by whoever opened an issue.
+Removing a server from the deployment's MCP settings is the only way to keep it
+out of these conversations.
+### Step 9 - Generate the automation script
+Read \`scripts/main.py\` from this skill's directory. Apply exactly six constant
+substitutions near the top of the file:
+> The script also reads a \`config.json\` shipped beside it, if there is one, over
+> these constants. That is how the catalog entry
+> (\`automations/catalog/gitlab-issue-to-mr/\`) configures an unmodified copy,
+> since a declarative host cannot rewrite Python. This setup path substitutes the
+> constants and ships no \`config.json\`, so the two never collide.
+| Placeholder | Replace with |
+|---|---|
+| \`PROJECTS = ["group/project"]\` | \`PROJECTS = ["{group_project}", ...]\` - one entry per project collected in Step 3 |
+| \`TRIGGER_LABEL = "openhands"\` | \`TRIGGER_LABEL = "{trigger_label}"\` |
+| \`BRANCH_PREFIX = "openhands/issue"\` | \`BRANCH_PREFIX = "{branch_prefix}"\` |
+| \`DRAFT_MERGE_REQUEST = True\` | \`DRAFT_MERGE_REQUEST = {True or False}\` |
+| \`GITLAB_API_URL = "https://gitlab.com/api/v4"\` | \`GITLAB_API_URL = "{gitlab_api_url}"\` |
+| \`AGENT_SECRET_NAMES: list[str] = ["GITLAB_TOKEN"]\` | \`AGENT_SECRET_NAMES: list[str] = ["{name}", ...]\` |
+Leave \`MAX_NEW_PER_RUN\` and \`DEFAULT_OPENHANDS_URL\` alone unless the user asks
+for a different cap or a non-default OpenHands URL.
+A project may be given as \`group/project\`, as a clone URL, or as an SSH remote;
+the script normalizes each one at startup and names the value it could not read
+rather than blaming the token. Subgroups are preserved.
+Use a safe string writer such as \`json.dumps(value)\` when inserting user-provided
+project paths, labels, or prefixes into Python string literals.
+\`json.dumps(list_of_projects)\` produces the whole \`PROJECTS\` list safely in one
+step.
+Write the customized script to a temporary build directory:
+\`\`\`bash
+mkdir -p /tmp/issue-to-mr-build
+# write the customized main.py to /tmp/issue-to-mr-build/main.py
+\`\`\`
+Validate syntax before packaging:
+\`\`\`bash
+python3 -m py_compile /tmp/issue-to-mr-build/main.py && echo "Syntax OK"
+\`\`\`
+Fix any syntax errors before proceeding.
+### Step 10 - Package and upload
+Determine the Automation backend URL and auth from the \`<RUNTIME_SERVICES>\`
+block in your system context:
+- **OPENHANDS_HOST**: the Automation backend \`url_from_agent\`
+- **Auth**: \`X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY\`
+\`\`\`bash
+tar -czf /tmp/issue-to-mr.tar.gz -C /tmp/issue-to-mr-build .
+TARBALL_PATH=$(curl -s -X POST \\
+  "\${OPENHANDS_HOST}/api/automation/v1/uploads?name=gitlab-issue-to-mr" \\
+  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \\
+  -H "Content-Type: application/gzip" \\
+  --data-binary @/tmp/issue-to-mr.tar.gz \\
+  | python3 -c "import json,sys; print(json.load(sys.stdin)['tarball_path'])")
+echo "Uploaded: $TARBALL_PATH"
+\`\`\`
+### Step 11 - Register the automation
+\`\`\`bash
+curl -s -X POST "\${OPENHANDS_HOST}/api/automation/v1" \\
+  -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d "{
+    \\"name\\": \\"GitLab Issue to MR: {project_summary} label {trigger_label}\\",
+    \\"trigger\\": {\\"type\\": \\"cron\\", \\"schedule\\": \\"{cron_schedule}\\"},
+    \\"tarball_path\\": \\"$TARBALL_PATH\\",
+    \\"entrypoint\\": \\"python3 main.py\\",
+    \\"timeout\\": 900
+  }" | python3 -m json.tool
+\`\`\`
+Use the single project as \`{project_summary}\` when there is one, and something
+like \`3 projects\` when there are several. A poll clones a project per queued
+issue and pushes finished branches, so the timeout allows for that; a run never
+waits for an agent to finish, only for it to be started.
+Record the returned \`id\`.
+### Step 12 - Confirm
+Tell the user:
+> ✅ **GitLab Issue to MR** is running!
+>
+> - Automation ID: \`{id}\`
+> - Projects: \`{group}/{project}\`, ... (one line each)
+> - GitLab API: \`{gitlab_api_url}\`
+> - Trigger label: \`{trigger_label}\`
+> - Branch prefix: \`{branch_prefix}\`
+> - Merge requests: \`{draft or ready for review}\`
+> - Polling schedule: \`{cron_schedule}\`
+> - State file per project:
+>   \`~/.openhands/workspaces/automation-state/gitlab_issue_to_mr_{id}_{group}__{project}.json\`
+>
+> Apply the \`{trigger_label}\` label to an issue to queue an implementation. Each
+> label event is processed once. To ask for another attempt, remove and re-apply
+> the label - that opens a second branch and merge request.
+>
+> The agent runs without a checkout credential; the automation pushes the branch
+> and opens the merge request once the agent has stopped.
+---
+## Runtime Behaviour (per poll)
+Each cron run executes \`main.py\`, which loads \`config.json\` if the catalog
+shipped one, checks that \`git\` is available, resolves and validates \`GITLAB_TOKEN\`
+once, then processes every project in \`PROJECTS\` independently. One project
+failing does not stop the others; the run fails only if every project fails.
+For each project:
+1. Loads that project's state (see \`references/state-schema.md\`) and reads its
+   default branch and clone URL.
+2. Lists open issues carrying \`TRIGGER_LABEL\`, newest-updated first. GitLab keeps
+   merge requests on their own endpoint, so labelling a merge request never
+   queues an implementation.
+3. For each labelled issue, up to \`MAX_NEW_PER_RUN\` new ones per run:
+   - Refetches the issue so a label removed since the listing does not start work.
+   - Finds the latest matching resource label event with \`action: "add"\`, and
+     skips it if that event has already been tracked.
+   - Picks the first free branch name, \`{BRANCH_PREFIX}-{iid}\` or a numbered
+     variant of it.
+   - Clones the default branch, shallow and single-branch, into
+     \`{WORKSPACE_BASE}/issue-to-mr/{group}__{project}/issue-{iid}-{event_id}\`,
+     sets the commit identity, and creates the branch. \`origin\` keeps its plain
+     HTTPS URL, so the workspace holds no credential.
+   - Starts an OpenHands conversation **whose working directory is that clone**,
+     told which issue to read, with the secrets named in \`AGENT_SECRET_NAMES\`
+     and the deployment's MCP servers attached.
+   - Comments on the issue with the branch, the label event, and the conversation
+     link.
+   - Records the task with \`status: "active"\`.
+   - If the clone or the conversation cannot be created, the clone is removed and
+     nothing is recorded, so the next poll retries the label event.
+4. For each active task:
+   - Abandons a conversation that has not reached a terminal status within two
+     hours, comments on the issue, and reclaims its clone.
+   - When the conversation reaches \`idle\`, \`finished\`, \`error\`, or \`stuck\`:
+     - Adopts the merge request the agent opened, if GitLab says one exists for
+       the branch, and comments its link on the issue. Everything below is the
+       path taken when it does not.
+     - Skips the merge request if the issue was closed meanwhile.
+     - Reports the problem on the issue if the conversation ended in \`error\` or
+       \`stuck\`.
+     - Commits whatever the agent left uncommitted, on top of any commits it made
+       itself.
+     - Posts the agent's answer on the issue, and opens no merge request, when
+       there are no commits at all - that is how an agent reports an issue too
+       ambiguous to implement.
+     - Otherwise pushes the branch, opens the merge request (draft by default,
+       titled \`Draft: [#42] <issue title>\`, with the agent's summary and
+       \`Closes #42\` in the description), and comments the link on the issue.
+     - A push or merge request that fails is retried on the next two polls before
+       the task is reported as failed, so a transient GitLab error does not throw
+       the work away.
+5. Removes the clone of every finished task, but only after confirming the
+   conversation has stopped - deleting it under a running agent would remove its
+   working directory. When that cannot be confirmed the directory is left alone
+   and the next poll tries again.
+6. Saves that project's state atomically.
+The completion callback fires once for the whole run.
+---
+## Additional Resources
+- **\`references/state-schema.md\`** - State JSON schema, field definitions, and the
+  task lifecycle.
+- **\`scripts/main.py\`** - The complete automation script. Customize the six
+  constants at the top before packaging.
+---
+## Troubleshooting
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Nothing is ever queued | Trigger label not present, or applied to a merge request rather than an issue | Apply the configured label to an issue |
+| "401 Unauthorized" in run logs | Token expired | Rotate and update \`GITLAB_TOKEN\` |
+| "The token's role on ... is below Developer" | The token has Reporter or Guest on that project | Grant Developer or above, or drop the project from \`PROJECTS\` |
+| Push rejected: "You are not allowed to push code to protected branches" | The branch prefix is covered by a protected-branch rule | Leave \`{BRANCH_PREFIX}-*\` unprotected |
+| Push rejected on \`.gitlab-ci.yml\` | The project protects its CI/CD configuration path | Allow the token's role to update it, or exclude such issues |
+| 404 on project access | Project path wrong, or no access | Re-check the entry in \`PROJECTS\` and the token's role. Subgroups must be included in full |
+| \`git is not available in the automation runtime\` | The runtime image has no git | Use a runtime image that ships git; the script clones, commits, and pushes with it |
+| Issue commented "did not change any code" | The agent judged the issue too ambiguous, or made no edits | Read its answer in the comment, add the missing detail to the issue, then re-apply the label |
+| Same issue not picked up again after new comments | Its label event was already processed | Remove and re-apply the trigger label |
+| Agent reports it cannot push or open an MR | By design - it has no push credentials in \`origin\` | No action; the automation pushes and opens the merge request after the agent stops |
+| \`Warning: could not fetch MCP config\` in run logs | The settings endpoint was unreachable | Non-fatal; the agent falls back to the REST calls in the prompt |
+| A backlog of labelled issues starts slowly | \`MAX_NEW_PER_RUN\` caps how many conversations one poll starts | Wait for the next polls, or raise the cap in the script |
+| Clones remain under \`issue-to-mr/\` | Their conversations had not stopped yet | They are removed by a later poll once the conversation is terminal |`,category:`automations`},{name:`incident-retrospective`,description:`Create an automation that drafts incident retrospectives. Gathers incident-channel messages from Slack, collects linked tickets and follow-ups from Linear, and publishes a retrospective draft to Notion with a timeline, impact summary, root-cause hypotheses, and action items.`,triggers:[`/incident-retro:setup`],content:`# Incident Retrospective Drafter Automation
 Set up an automation that drafts incident retrospectives by pulling data from
 Slack, Linear, and Notion.
@@ -4928,7 +5390,7 @@ The agent server typically runs inside a **sandbox** (a Docker or Kubernetes con
 |---|---|---|
 | \`RUNTIME_URL\` | Ambient in cloud environments | Public-facing URL of the **agent server** sandbox. Use this to determine whether external webhook delivery is possible — if unset or local, webhooks cannot be received. The automation service may run at a separate URL (see Determining the API Host). |
 | \`AGENT_SERVER_URL\` | Injected into scripts at run time only | Internal URL of the agent server. Available inside script execution context; **not** an ambient environment variable outside of a running script. |
-| \`OPENHANDS_HOST\` | Shell convention only — set manually | Base URL for the automation service API. **Not a real environment variable.** Set it from the \`<HOST>\` system-prompt value, or default to \`https://app.all-hands.dev\`. Used in all \`curl\` examples throughout this skill. |
+| \`OPENHANDS_HOST\` | Shell convention only — set manually | Base URL for the automation service API. **Not a real environment variable.** Set it from an explicit host, a detected local Agent Canvas server, or the cloud default. Used in all \`curl\` examples throughout this skill. |
 > **⚠️ CRITICAL — Agent behavior rules:**
 >
@@ -4993,11 +5455,17 @@ Entrypoint must be \`python3 main.py\` (no \`setup.sh\` needed). Wrap your main
 ## Authentication
-All requests require Bearer authentication:
+All requests require authentication:
-\`\`\`bash
--H "Authorization: Bearer \${OPENHANDS_API_KEY}"
-\`\`\`
+- Cloud (default \`https://app.all-hands.dev\`): Bearer token:
+  \`-H "Authorization: Bearer \${OPENHANDS_API_KEY}"\`
+- Local Agent Canvas (\`http://localhost:8001\`): session API key through \`X-Session-API-Key\`:
+  \`-H "X-Session-API-Key: \${OPENHANDS_AUTOMATION_API_KEY:-\${SESSION_API_KEY}}"\`
+The curl examples below show cloud Bearer authentication. For local Agent Canvas, replace that header with the \`X-Session-API-Key\` header above.
 ## API Endpoints
@@ -5007,14 +5475,18 @@ All requests require Bearer authentication:
 The automation service may run at a different URL from the agent server. In the examples throughout this skill, \`\${OPENHANDS_HOST}\` is a shell-variable convention for the automation service base URL — it is **not** a real environment variable. Set it from context before running any curl command:
-- Look for a \`<HOST>\` value in the system prompt. If present, use that URL.
+- Look for a \`<HOST>\` value in the system prompt or runtime-services block. If present, use that URL.
+- If running inside a local Agent Canvas stack and no explicit host is provided, use \`http://localhost:8001\` for the local automation/agent-server API.
 - Otherwise default to \`https://app.all-hands.dev\`.
+For a local Agent Canvas server, validate the endpoint before making a mutating request and authenticate with the session key through \`X-Session-API-Key\` when that API requires it. Do not use the cloud default merely because no \`<HOST>\` value is present.
 \`\`\`bash
-OPENHANDS_HOST="https://app.all-hands.dev"  # replace with <HOST> if provided
+# Choose the host that matches the detected environment:
+OPENHANDS_HOST="http://localhost:8001"       # local Agent Canvas
+# OPENHANDS_HOST="https://app.all-hands.dev" # OpenHands Cloud
 \`\`\`
 ### Automation Endpoints
 | Endpoint | Method | Description |
@@ -5766,233 +6238,328 @@ See \`references/security.md\` — also covers narrowing triggers and sender-lev
 - **\`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/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.`,category:`automations`,defaultEnabled:!0},{name:`openhands-sdk`,description:`Reference skill for the OpenHands Software Agent SDK - the Python framework for building AI agents that write software. Use when you need to build agents with the SDK, create custom tools, configure LLMs, manage conversations, delegate to sub-agents, or deploy agents locally or remotely.`,triggers:[`openhands-sdk`,`openhands sdk`,`software-agent-sdk`,`agent-sdk`,`/sdk`],content:`# OpenHands Software Agent SDK
+- **\`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.`,category:`automations`,defaultEnabled:!0},{name:`openhands-enterprise-troubleshooting`,description:`This skill should be used when a user reports an issue with OpenHands Enterprise (OHE) on a self-hosted (Replicated VM-based) installation. Use for diagnosing sandbox startup failures, auth issues, certificate errors, LLM connectivity problems, Keycloak login issues, Replicated Admin Console access, upgrade failures, or resource exhaustion. Helps triage symptoms, run diagnostic commands, guide through recovery steps, generate and analyze Replicated support bundles offline, and produce escalation handoffs.`,triggers:[`openhands enterprise`,`OHE troubleshooting`,`openhands not working`,`sandbox failed`,`replicated admin console`,`keycloak login`,`certificate error`,`LLM connectivity`,`upgrade failed`,`support bundle`,`openhands install`],content:`# OpenHands Enterprise Troubleshooting
-All SDK documentation lives at <https://docs.openhands.dev/sdk>.
+This skill helps diagnose and resolve common issues on OpenHands Enterprise (OHE) self-hosted installations using Replicated. It covers triage, guided recovery, support bundle generation, and escalation handoffs.
-For the full topic index, fetch <https://docs.openhands.dev/llms.txt> and read
-the "OpenHands Software Agent SDK" section.
+## Diagnostic Workflow
-## Quick reference
+When a user reports an OHE issue:
-Install: \`pip install openhands-sdk openhands-tools\`
+1. **Collect symptoms** - Ask user to describe what they see, error messages, when it started
+2. **Identify failure mode** - Match symptoms to one of the common issues below
+3. **Run targeted diagnostics** - Use commands in \`references/diagnostics.md\`
+4. **Guide recovery** - Follow resolution steps for the identified issue, one at a time
+5. **Verify fix** - Confirm the original symptom is gone, not just that the last command succeeded
+6. **Generate handoff** - If unresolved, produce a clear summary for the OpenHands team
-\`\`\`python
-import os
+Take recovery one step at a time. Before each step, state what it will change and what you expect to
+see afterwards; after it, run the check that confirms it before moving on. If the check fails or
+shows something unexpected, stop and re-diagnose — a step applied on top of a failed one buries the
+evidence, and several applied blind can leave the install worse than the fault you started with.
+Destructive steps (restarts, rollbacks, config changes) need the user's agreement first, and are
+worth recording as you go so the handoff can say exactly what was changed.
-from openhands.sdk import LLM, Agent, Conversation, Tool
-from openhands.tools.file_editor import FileEditorTool
-from openhands.tools.task_tracker import TaskTrackerTool
-from openhands.tools.terminal import TerminalTool
+Work from whatever the user has. A described symptom starts at step 1; a support bundle goes to
+[Analyzing the Support Bundle](#analyzing-the-support-bundle). If they paste raw log output, the
+triage method in
+[\`references/support-bundle-analysis.md\`](references/support-bundle-analysis.md#triaging-a-log-file)
+applies to pasted text as well as to files, and notes what a hand-picked excerpt can hide.
+## Common Failure Modes
-llm = LLM(
-    model=os.getenv("LLM_MODEL", "gpt-5.5"),
-    api_key=os.getenv("LLM_API_KEY"),
-    base_url=os.getenv("LLM_BASE_URL", None),
-)
+### 1. Sandbox Fails to Start / Timeout
-agent = Agent(
-    llm=llm,
-    tools=[
-        Tool(name=TerminalTool.name),
-        Tool(name=FileEditorTool.name),
-        Tool(name=TaskTrackerTool.name),
-    ],
-)
+**Symptoms:**
+- Conversation hangs then times out
+- "Sandbox failed to start" error
+- A timeout in the logs. Read the actual value rather than assuming one: the timeouts in
+  \`runtime-api\` are configurable and differ between the Kubernetes client and the app, so quoting a
+  fixed number back to a customer is how you end up chasing the wrong one.
+**Diagnosis:** Check sandbox service status, the \`sysbox-runc\` RuntimeClass and its containerd
+runtime, resource availability
-cwd = os.getcwd()
-conversation = Conversation(agent=agent, workspace=cwd)
+**Reference:** See \`references/diagnostics.md\` - Section "Sandbox Startup"
-conversation.send_message("Write 3 facts about the current project into FACTS.txt.")
-conversation.run()
-print("All done!")
+### 2. Git Provider Auth Broken
+**Symptoms:**
+- "Authentication failed" for the configured provider
+- Can't clone or push repos
+- The provider shows as disconnected
+**Diagnosis:** Check the provider's secret in Kubernetes and that the provider is enabled. GitHub,
+GitLab, Bitbucket Data Center, and Azure DevOps are each configured separately — confirm which one
+the user is actually on before diagnosing
+**Reference:** See \`references/diagnostics.md\` - Section "Git Provider Auth"
+### 3. Certificate Errors
+**Symptoms:**
+- "certificate expired" or "self-signed certificate" errors
+- TLS handshake failures
+- Browser shows insecure connection warning
+**Diagnosis:** Check cert expiry, certificate chain, ingress configuration
+**Reference:** See \`references/diagnostics.md\` - Section "Certificate Issues"
+### 4. LLM Connectivity Failures
+**Symptoms:**
+- "LLM endpoint unreachable"
+- "Authentication failed" for LLM API
+- Conversations fail to start
+**Diagnosis:** Check LLM endpoint URL, API key secrets, network policies
+**Reference:** See \`references/diagnostics.md\` - Section "LLM Connectivity"
+### 5. Keycloak Login Issues
+**Symptoms:**
+- Can't access admin console
+- Login loop or "invalid credentials"
+- Keycloak pod showing errors
+**Diagnosis:** Check Keycloak pod status, database connectivity, realm configuration
+**Reference:** See \`references/diagnostics.md\` - Section "Keycloak"
+### 6. Replicated Admin Console Unreachable
+**Symptoms:**
+- Can't access admin console URL
+- Connection refused or timeout
+- Browser shows "site cannot be reached"
+**Diagnosis:** Check Replicated operator pod, ingress, service endpoints
+**Reference:** See \`references/diagnostics.md\` - Section "Replicated Admin Console"
+### 7. Upgrade Stuck or Failed
+**Symptoms:**
+- Replicated shows upgrade as "failed"
+- Pods in crash loop after upgrade
+- Migration jobs failing
+**Diagnosis:** Check failed job logs, resource availability, pre-flight failures
+**Reference:** See \`references/diagnostics.md\` - Section "Upgrade Issues"
+### 8. OOM / Resource Exhaustion
+**Symptoms:**
+- Pods being OOMKilled
+- "Too many open files" errors
+- Services becoming unresponsive
+**Diagnosis:** Check node resources (memory, disk, file descriptors)
+**Reference:** See \`references/diagnostics.md\` - Section "Resource Exhaustion"
+## Diagnostic Commands Quick Reference
+Access the VM and run these common commands.
+**An empty result never means "healthy".** \`kubectl get pods -l <selector>\` prints \`No resources
+found\` and exits 0 both when a component is down and when the selector is wrong, so the two are
+indistinguishable. When you need to know whether something is running, ask its Deployment or
+StatefulSet for a READY count instead — that object exists either way, and \`0/1\` means down while a
+\`NotFound\` error means you had the name wrong.
+\`\`\`bash
+# Is it up? READY answers this; an empty pod list does not.
+kubectl get deploy,statefulset -n openhands
+# Check overall pod status
+kubectl get pods -n openhands
+# View pod logs (replace POD_NAME)
+kubectl logs -n openhands POD_NAME
+kubectl logs -n openhands POD_NAME --previous
+# Describe a pod for events
+kubectl describe pod -n openhands POD_NAME
+# Check resource usage
+kubectl top nodes
+kubectl top pods -n openhands
+# Check certificate expiry
+echo | openssl s_client -connect HOST:443 2>/dev/null | openssl x509 -noout -dates
+# Check the Replicated components. On Embedded Cluster these are the Admin
+# Console in \`kotsadm\`, the operator in \`embedded-cluster\`, and the Replicated
+# SDK in \`openhands\` under app.kubernetes.io/name=replicated. A \`replicated\`
+# namespace belongs to the older kURL topology and is absent here.
+kubectl get pods -n kotsadm
+kubectl get pods -n embedded-cluster
+kubectl get pods -n openhands -l app.kubernetes.io/name=replicated
 \`\`\`
-## Core classes (\`openhands.sdk\`)
+## Support Bundle Generation
+When the issue requires deeper investigation — or before escalating — generate a support bundle. It
+captures both host- and cluster-level state in one archive.
+### Generating the Support Bundle
+SSH to the VM, then from the directory containing the installer binary:
+\`\`\`bash
+sudo ./openhands support-bundle
+\`\`\`
-| Class | Purpose |
+This uses the default Embedded Cluster spec to collect cluster- *and* host-level information, and
+automatically includes the OpenHands application-specific collectors. Run it on a **controller
+node** — on a non-controller node it cannot capture cluster-wide information.
+For Embedded Cluster versions earlier than 1.17.0, use the support-bundle plugin from within the
+cluster shell instead:
+\`\`\`bash
+sudo ./openhands shell
+kubectl support-bundle --load-cluster-specs /var/lib/embedded-cluster/support/host-support-bundle.yaml
+\`\`\`
+The bundle is written to the working directory as \`support-bundle-<UTC timestamp>.tar.gz\`. Share it
+with the OpenHands team, or analyze it directly with the steps below.
+Support bundles carry potentially sensitive data. Replicated's redactor masks common secret patterns
+as \`***HIDDEN***\`, but it is not a guarantee — hostnames, user and installation identifiers, and
+config values routinely survive it. Treat a bundle as confidential, send it only through the channel
+the OpenHands team gives you, and avoid pasting raw excerpts into public issues or chats.
+### Analyzing the Support Bundle
+**Full guide: [\`references/support-bundle-analysis.md\`](references/support-bundle-analysis.md).**
+Read it before drawing conclusions — the bundle's layout is not what you would guess from \`kubectl\`,
+and several of its gaps produce convincing false negatives.
+Fast path — the bundled triage script reconstructs the standard first pass (cluster meta, analyzer
+results, pod table, OOM and restart scan, \`top\` equivalent, allocatable headroom, events) in one
+command. It reports; the ranking and the diagnosis are yours to make:
+\`\`\`bash
+tar -xzf support-bundle-2026-07-28T06_54_18.tar.gz
+python3 scripts/bundle_triage.py support-bundle-2026-07-28T06_54_18
+\`\`\`
+You are reading this bundle because something is broken, so treat a clean run as "not here" rather
+than "nothing wrong" — the script sees pod objects, analyzer verdicts, node conditions and resource
+totals, and reads no application logs at all. \`references/support-bundle-analysis.md\` has a section
+on where to look next when the objects come back clean.
+Then the four things that most often answer the question outright:
+| Question | Where to look |
 |---|---|
-| [\`Agent\`](https://docs.openhands.dev/sdk/arch/agent.md) | Reasoning-action loop |
-| [\`Condenser\`](https://docs.openhands.dev/sdk/arch/condenser.md) | Conversation history compression system |
-| [\`Conversation\`](https://docs.openhands.dev/sdk/arch/conversation.md) | Conversation orchestration system |
-| [\`Event\`](https://docs.openhands.dev/sdk/arch/events.md) | Typed event framework |
-| [\`LLM\`](https://docs.openhands.dev/sdk/arch/llm.md) | Provider-agnostic language model interface |
-| [\`SecurityAnalyzer\`](https://docs.openhands.dev/sdk/arch/security.md) | Action security analysis and validation |
-| [\`Skill\`](https://docs.openhands.dev/sdk/arch/skill.md) | Reusable prompt system |
-| [\`Tool / ToolDefinition\`](https://docs.openhands.dev/sdk/arch/tool-system.md) | Action-observation tool framework |
-| [\`Workspace\`](https://docs.openhands.dev/sdk/arch/workspace.md) | Execution environment abstraction |
-## API reference
-[\`openhands.sdk.agent\`](https://docs.openhands.dev/sdk/api-reference/openhands.sdk.agent.md), [\`openhands.sdk.conversation\`](https://docs.openhands.dev/sdk/api-reference/openhands.sdk.conversation.md), [\`openhands.sdk.event\`](https://docs.openhands.dev/sdk/api-reference/openhands.sdk.event.md), [\`openhands.sdk.llm\`](https://docs.openhands.dev/sdk/api-reference/openhands.sdk.llm.md), [\`openhands.sdk.security\`](https://docs.openhands.dev/sdk/api-reference/openhands.sdk.security.md), [\`openhands.sdk.tool\`](https://docs.openhands.dev/sdk/api-reference/openhands.sdk.tool.md), [\`openhands.sdk.utils\`](https://docs.openhands.dev/sdk/api-reference/openhands.sdk.utils.md), [\`openhands.sdk.workspace\`](https://docs.openhands.dev/sdk/api-reference/openhands.sdk.workspace.md)
-## Guides
-- [ACP Agent](https://docs.openhands.dev/sdk/guides/agent-acp.md): Delegate to an ACP-compatible server (Claude Code, Gemini CLI, etc.) instead of calling an LLM directly.
-- [Agent Settings](https://docs.openhands.dev/sdk/guides/agent-settings.md): Configure, serialize, and recreate agents from structured settings.
-- [Agent Skills & Context](https://docs.openhands.dev/sdk/guides/skill.md): Skills add specialized behaviors, domain knowledge, and context-aware triggers to your agent through structured prompts.
-- [API-based Sandbox](https://docs.openhands.dev/sdk/guides/agent-server/api-sandbox.md): Connect to hosted API-based agent server for fully managed infrastructure.
-- [Apptainer Sandbox](https://docs.openhands.dev/sdk/guides/agent-server/apptainer-sandbox.md): Run agent server in rootless Apptainer containers for HPC and shared computing environments.
-- [Ask Agent Questions](https://docs.openhands.dev/sdk/guides/convo-ask-agent.md): Get sidebar replies from the agent during conversation execution without interrupting the main flow.
-- [Assign Reviews](https://docs.openhands.dev/sdk/guides/github-workflows/assign-reviews.md): Automate PR management with intelligent reviewer assignment and workflow notifications using OpenHands Agent
-- [Browser Session Recording](https://docs.openhands.dev/sdk/guides/browser-session-recording.md): Record and replay your agent's browser sessions using rrweb.
-- [Browser Use](https://docs.openhands.dev/sdk/guides/agent-browser-use.md): Enable web browsing and interaction capabilities for your agent.
-- [Context Condenser](https://docs.openhands.dev/sdk/guides/context-condenser.md): Manage agent memory by condensing conversation history to save tokens.
-- [Conversation Goals](https://docs.openhands.dev/sdk/guides/agent-server/conversation-goals.md): Add a resumable goal strategy to a normal agent-server conversation.
-- [Conversation with Async](https://docs.openhands.dev/sdk/guides/convo-async.md): Use async/await for concurrent agent operations and non-blocking execution.
-- [Creating Custom Agent](https://docs.openhands.dev/sdk/guides/agent-custom.md): Learn how to design specialized agents with custom tool sets
-- [Critic (Experimental)](https://docs.openhands.dev/sdk/guides/critic.md): Real-time evaluation of agent actions using an LLM-based critic model, with built-in iterative refinement.
-- [Custom Tools](https://docs.openhands.dev/sdk/guides/custom-tools.md): Tools define what agents can do. The SDK includes built-in tools for common operations and supports creating custom tools for specialized needs.
-- [Custom Tools with Remote Agent Server](https://docs.openhands.dev/sdk/guides/agent-server/custom-tools.md): Learn how to use custom tools with a remote agent server by building a custom base image that includes your tool implementations.
-- [Custom Visualizer](https://docs.openhands.dev/sdk/guides/convo-custom-visualizer.md): Customize conversation visualization by creating custom visualizers or configuring the default visualizer.
-- [Deferred Init (Warm-Pool)](https://docs.openhands.dev/sdk/guides/agent-server/deferred-init.md): Pre-warm agent-server pods before a user is matched, then activate them at runtime with POST /api/init.
-- [Docker Sandbox](https://docs.openhands.dev/sdk/guides/agent-server/docker-sandbox.md): Run agent server in isolated Docker containers for security and reproducibility.
-- [Exception Handling](https://docs.openhands.dev/sdk/guides/llm-error-handling.md): Provider‑agnostic exceptions raised by the SDK and recommended patterns for handling them.
-- [FAQ](https://docs.openhands.dev/sdk/faq.md): Frequently asked questions about the OpenHands SDK
-- [File-Based Agents](https://docs.openhands.dev/sdk/guides/agent-file-based.md): Define specialized sub-agents as simple Markdown files with YAML frontmatter — no Python code required.
-- [Fork a Conversation](https://docs.openhands.dev/sdk/guides/convo-fork.md): Branch off an existing conversation for follow-up exploration without contaminating the original.
-- [Getting Started](https://docs.openhands.dev/sdk/getting-started.md): Install the OpenHands SDK and build AI agents that write software.
-- [Goal Completion Loop](https://docs.openhands.dev/sdk/guides/convo-goal.md): Drive a conversation toward a verifiable objective with a judge-driven, self-continuing completion loop.
-- [GPT-5 Preset (ApplyPatchTool)](https://docs.openhands.dev/sdk/guides/llm-gpt5-preset.md): Use the GPT-5 preset to build an agent that swaps the standard FileEditorTool for ApplyPatchTool.
-- [Hello World](https://docs.openhands.dev/sdk/guides/hello-world.md): The simplest possible OpenHands agent - configure an LLM, create an agent, and complete a task.
-- [Hooks](https://docs.openhands.dev/sdk/guides/hooks.md): Use lifecycle hooks to observe, log, and customize agent execution.
-- [Image Input](https://docs.openhands.dev/sdk/guides/llm-image-input.md): Send images to multimodal agents for vision-based tasks and analysis.
-- [Interactive Terminal](https://docs.openhands.dev/sdk/guides/agent-interactive-terminal.md): Enable agents to interact with terminal applications like ipython, python REPL, and other interactive CLI tools.
-- [Iterative Refinement](https://docs.openhands.dev/sdk/guides/iterative-refinement.md): Implement iterative refinement workflows where agents refine their work based on critique feedback until quality thresholds are met.
-- [LLM Fallback Strategy](https://docs.openhands.dev/sdk/guides/llm-fallback.md): Automatically try alternate LLMs when the primary model fails with a transient error.
-- [LLM Profile Store](https://docs.openhands.dev/sdk/guides/llm-profile-store.md): Save, load, and manage reusable LLM configurations so you never repeat setup code again.
-- [LLM Registry](https://docs.openhands.dev/sdk/guides/llm-registry.md): Dynamically select and configure language models using the LLM registry.
-- [LLM Streaming](https://docs.openhands.dev/sdk/guides/llm-streaming.md): Stream LLM responses token-by-token for real-time display and interactive user experiences.
-- [LLM Subscriptions](https://docs.openhands.dev/sdk/guides/llm-subscriptions.md): Use your ChatGPT Plus/Pro subscription to access Codex models without consuming API credits.
-- [Local Agent Server](https://docs.openhands.dev/sdk/guides/agent-server/local-server.md): Install and run an OpenHands Agent Server on your machine, then connect to it from the SDK.
-- [Metrics Tracking](https://docs.openhands.dev/sdk/guides/metrics.md): Track token usage, costs, and latency metrics for your agents.
-- [Model Context Protocol](https://docs.openhands.dev/sdk/guides/mcp.md): Model Context Protocol (MCP) enables dynamic tool integration from external servers. Agents can discover and use MCP-provided tools automatically.
-- [Model Routing](https://docs.openhands.dev/sdk/guides/llm-routing.md): Route agent's LLM requests to different models.
-- [Observability & Tracing](https://docs.openhands.dev/sdk/guides/observability.md): Enable OpenTelemetry tracing to monitor and debug your agent's execution with tools like Laminar, MLflow, Honeycomb, or any OTLP-compatible backend.
-- [OpenAI-Compatible Endpoint](https://docs.openhands.dev/sdk/guides/agent-server/openai-gateway.md): Call an OpenHands agent-server through the OpenAI Chat Completions protocol.
-- [OpenHands Cloud Workspace](https://docs.openhands.dev/sdk/guides/agent-server/cloud-workspace.md): Connect to OpenHands Cloud for fully managed sandbox environments with optional SaaS credential inheritance.
-- [Overview](https://docs.openhands.dev/sdk/guides/agent-server/overview.md): Run agents on remote servers with isolated workspaces for production deployments.
-- [Parallel Tool Execution](https://docs.openhands.dev/sdk/guides/parallel-tool-execution.md): Execute multiple tools concurrently within a single LLM response to improve throughput for independent operations.
-- [Pause and Resume](https://docs.openhands.dev/sdk/guides/convo-pause-and-resume.md): Pause agent execution, perform operations, and resume without losing state.
-- [Persistence](https://docs.openhands.dev/sdk/guides/convo-persistence.md): Save and restore conversation state for multi-session workflows.
-- [Persistent Memory](https://docs.openhands.dev/sdk/guides/persistent-memory.md): Give agents opt-in, two-tier memory that survives across conversations.
-- [Plugins](https://docs.openhands.dev/sdk/guides/plugins.md): Plugins bundle skills, hooks, MCP servers, agents, and commands into reusable packages that extend agent capabilities.
-- [PR Review](https://docs.openhands.dev/sdk/guides/github-workflows/pr-review.md): Use OpenHands Agent to generate meaningful pull request review
-- [Reasoning](https://docs.openhands.dev/sdk/guides/llm-reasoning.md): Access model reasoning traces from Anthropic extended thinking and OpenAI responses API.
-- [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.
-- [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.
-- [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
-## Examples
-Source: [\`examples/\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples)
-### [\`01_standalone_sdk/\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk)
-- [\`01_hello_world.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/01_hello_world.py)
-- [\`02_custom_tools.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/02_custom_tools.py)
-- [\`03_activate_skill.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/03_activate_skill.py)
-- [\`04_confirmation_mode_example.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/04_confirmation_mode_example.py)
-- [\`05_use_llm_registry.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/05_use_llm_registry.py)
-- [\`06_interactive_terminal_w_reasoning.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/06_interactive_terminal_w_reasoning.py)
-- [\`07_mcp_integration.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/07_mcp_integration.py)
-- [\`08_mcp_with_oauth.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/08_mcp_with_oauth.py)
-- [\`09_pause_example.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/09_pause_example.py)
-- [\`10_persistence.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/10_persistence.py)
-- [\`11_async.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/11_async.py)
-- [\`12_custom_secrets.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/12_custom_secrets.py)
-- [\`13_get_llm_metrics.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/13_get_llm_metrics.py)
-- [\`14_context_condenser.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/14_context_condenser.py)
-- [\`15_browser_use.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/15_browser_use.py)
-- [\`16_llm_security_analyzer.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/16_llm_security_analyzer.py)
-- [\`17_image_input.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/17_image_input.py)
-- [\`18_send_message_while_processing.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/18_send_message_while_processing.py)
-- [\`19_llm_routing.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/19_llm_routing.py)
-- [\`20_stuck_detector.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/20_stuck_detector.py)
-- [\`21_generate_extraneous_conversation_costs.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/21_generate_extraneous_conversation_costs.py)
-- [\`22_anthropic_thinking.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/22_anthropic_thinking.py)
-- [\`23_responses_reasoning.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/23_responses_reasoning.py)
-- [\`24_planning_agent_workflow.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/24_planning_agent_workflow.py)
-- [\`25_agent_delegation.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/25_agent_delegation.py)
-- [\`26_custom_visualizer.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/26_custom_visualizer.py)
-- [\`27_observability_laminar.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/27_observability_laminar.py)
-- [\`28_ask_agent_example.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/28_ask_agent_example.py)
-- [\`29_llm_streaming.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/29_llm_streaming.py)
-- [\`30_tom_agent.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/30_tom_agent.py)
-- [\`31_iterative_refinement.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/31_iterative_refinement.py)
-- [\`32_configurable_security_policy.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/32_configurable_security_policy.py)
-- [\`33_hooks\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk/33_hooks)
-- [\`34_critic_example.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/34_critic_example.py)
-- [\`35_subscription_login.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/35_subscription_login.py)
-- [\`36_event_json_to_openai_messages.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/36_event_json_to_openai_messages.py)
-- [\`37_llm_profile_store\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk/37_llm_profile_store)
-- [\`38_browser_session_recording.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/38_browser_session_recording.py)
-- [\`39_llm_fallback.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/39_llm_fallback.py)
-- [\`40_acp_agent_example.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/40_acp_agent_example.py)
-- [\`41_task_tool_set.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/41_task_tool_set.py)
-- [\`42_file_based_subagents.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/42_file_based_subagents.py)
-- [\`44_model_switching_in_convo.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/44_model_switching_in_convo.py)
-- [\`45_parallel_tool_execution.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/45_parallel_tool_execution.py)
-- [\`46_agent_settings.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/46_agent_settings.py)
-- [\`47_defense_in_depth_security.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/47_defense_in_depth_security.py)
-- [\`48_conversation_fork.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/48_conversation_fork.py)
-- [\`49_switch_llm_tool.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/49_switch_llm_tool.py)
-- [\`50_async_cancellation.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/50_async_cancellation.py)
-- [\`51_agent_hooks\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk/51_agent_hooks)
-- [\`52_dynamic_workflow.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/52_dynamic_workflow.py)
-- [\`53_client_defined_tools.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/53_client_defined_tools.py)
-- [\`54_goal_completion_loop.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/54_goal_completion_loop.py)
-- [\`55_persistent_memory.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/55_persistent_memory.py)
-- [\`56_structured_output.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/56_structured_output.py)
-- [\`57_prompt_hooks\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk/57_prompt_hooks)
-- [\`58_ask_oracle_tool\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk/58_ask_oracle_tool)
-### [\`02_remote_agent_server/\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/02_remote_agent_server)
-- [\`01_convo_with_local_agent_server.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/01_convo_with_local_agent_server.py)
-- [\`02_convo_with_docker_sandboxed_server.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/02_convo_with_docker_sandboxed_server.py)
-- [\`03_browser_use_with_docker_sandboxed_server.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/03_browser_use_with_docker_sandboxed_server.py)
-- [\`04_convo_with_api_sandboxed_server.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/04_convo_with_api_sandboxed_server.py)
-- [\`05_vscode_with_docker_sandboxed_server.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/05_vscode_with_docker_sandboxed_server.py)
-- [\`06_custom_tool\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/02_remote_agent_server/06_custom_tool)
-- [\`07_convo_with_cloud_workspace.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/07_convo_with_cloud_workspace.py)
-- [\`08_convo_with_apptainer_sandboxed_server.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/08_convo_with_apptainer_sandboxed_server.py)
-- [\`09_acp_agent_with_remote_runtime.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/09_acp_agent_with_remote_runtime.py)
-- [\`10_cloud_workspace_share_credentials.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/10_cloud_workspace_share_credentials.py)
-- [\`11_conversation_fork.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/11_conversation_fork.py)
-- [\`12_settings_and_secrets_api.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/12_settings_and_secrets_api.py)
-- [\`13_workspace_get_llm.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/13_workspace_get_llm.py)
-- [\`14_client_defined_tools.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/14_client_defined_tools.py)
-- [\`15_openai_compatible_gateway.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/15_openai_compatible_gateway.py)
-- [\`16_deferred_init.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/16_deferred_init.py)
-- [\`hook_scripts\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/02_remote_agent_server/hook_scripts)
-- [\`scripts\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/02_remote_agent_server/scripts)
-### [\`03_github_workflows/\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows)
-- [\`01_basic_action\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/01_basic_action)
-- [\`02_pr_review\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/02_pr_review)
-- [\`03_todo_management\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/03_todo_management)
-- [\`04_datadog_debugging\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/04_datadog_debugging)
-- [\`05_posthog_debugging\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/05_posthog_debugging)
-### [\`04_llm_specific_tools/\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/04_llm_specific_tools)
-- [\`01_gpt5_apply_patch_preset.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/04_llm_specific_tools/01_gpt5_apply_patch_preset.py)
-- [\`02_gemini_file_tools.py\`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/04_llm_specific_tools/02_gemini_file_tools.py)
-### [\`05_skills_and_plugins/\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/05_skills_and_plugins)
-- [\`01_loading_agentskills\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/05_skills_and_plugins/01_loading_agentskills)
-- [\`02_loading_plugins\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/05_skills_and_plugins/02_loading_plugins)
-- [\`03_managing_installed_skills\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/05_skills_and_plugins/03_managing_installed_skills)
-- [\`04_mixed_marketplace_skills\`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/05_skills_and_plugins/04_mixed_marketplace_skills)`,category:`agent-authoring`,defaultEnabled:!0},{name:`pdflatex`,description:`Install and use pdflatex to compile LaTeX documents into PDFs on Linux. Use when generating academic papers, research publications, or any documents written in LaTeX.`,triggers:[`pdflatex`],content:`PdfLatex is a tool that converts Latex sources into PDF. This is specifically very important for researchers, as they use it to publish their findings. It could be installed very easily using Linux terminal, though this seems an annoying task on Windows. Installation commands are given below.
+| What did the collector already conclude? | \`analysis.json\` — pre-computed verdicts, highest-value file in the bundle |
+| What is each pod actually doing? | \`cluster-resources/pods/<namespace>.json\` |
+| What did a container log? | \`cluster-resources/pods/logs/<ns>/<pod>/<container>.log\` |
+| What is the install running? | \`kots/admin_console/app-info.json\` — version, channel, sequence |
+Four traps worth knowing before you start:
+- **Never use file mtimes for timing.** They record when you extracted the archive. Take the capture
+  time from the bundle directory name, which is UTC.
+- **Log filenames are container names, not pod names.** Init-container failures (\`migrate-db\`,
+  \`wait-for-db\`) are invisible to \`kubectl logs <pod>\` and are the easiest real failure to miss.
+- **\`***HIDDEN***\` means "redacted", not "unset".** The redactor over-redacts, including non-secrets.
+- **Check a log's format before filtering it.** Most bundle logs are plain text, not JSON, and \`jq\`
+  aborts on the first non-JSON line — so a severity filter can print nothing on a file full of
+  errors. Prefix with \`grep '^{'\`, and read the non-JSON lines separately.
+Once triage points at a failure mode, use \`references/diagnostics.md\` for that mode's specific
+commands and error patterns.
+### Summarizing the Bundle: Most Likely Root Cause
+The script reports; deciding which of its observations explains the user's symptom is your job. Work
+through its output in this order, because it is roughly the order in which a finding is likely to be
+the actual cause rather than a side effect.
+**1. Start from the symptom and the clock, not from the output.** Get the capture time from the
+bundle directory name (UTC) and establish when the user says it broke. A finding that predates the
+symptom by weeks is background; one that starts within the window is a candidate. Ages in the pod
+table are the cheapest way to place an event in time.
+**2. Read \`analysis.json\` first — but not literally.** The collector's own verdicts are the
+highest-value content in the bundle. Two cautions when reading them through the script: everything
+non-passing prints under a \`FAIL\` heading, including \`warn\`-severity entries that may be advisory,
+so check the severity in \`analysis.json\` before calling one a failure; and per-object analyzers are
+collapsed into families with one example each, so \`[x12]\` means twelve objects affected and the
+example shown is arbitrary. Open the file directly before quoting an analyzer verdict to a customer.
+**3. Rank what remains by how directly it explains the symptom.** In descending order of
+usefulness — a container in \`CrashLoopBackOff\` or actively OOM-killed right now; a pod that never
+started (\`Pending\`, \`CreateContainerConfigError\`, an init container that never completed); a pod
+that is \`Running\` but not \`Ready\`, which fails a health check and takes traffic out of rotation; a
+node condition that is genuinely bad; and resource pressure, which is usually a consequence rather
+than a cause. A recovered termination — visible only as \`lastState\` with an older age — explains a
+past blip, not a live outage; do not lead with one.
+**4. Prefer the cause nearest the symptom.** A failed \`migrate-db\` init container and an app pod
+stuck \`Pending\` are one finding, not two, and the init container is the one to report. When several
+findings share a timestamp, look for the common dependency rather than listing all of them.
+**5. Say what you ruled out.** The script reads pod objects, analyzer verdicts, node conditions and
+resource totals — and no application logs. If nothing in the objects explains the symptom, that is
+itself a result: it puts the cause in the application logs, in the network path, or outside the
+cluster. Name which, rather than reporting that the bundle looked healthy.
+State the conclusion with its evidence and its confidence — the object or analyzer it rests on, and
+whether it explains the reported symptom or merely coincides with it. A ranked shortlist of two or
+three candidates is more useful than a single confident guess, and it drops straight into the
+**Likely Root Cause** field of the handoff template below.
+## Escalation Handoff Template
+When an issue cannot be resolved, produce this summary:
+\`\`\`
+## Issue Summary
+**Problem:** [One-line description]
+**Duration:** [When it started]
+**Impact:** [Who is affected]
+## Symptoms Observed
+- [Symptom 1]
+- [Symptom 2]
+## Diagnostic Steps Taken
+1. [Step 1]
+2. [Step 2]
+## Logs / Evidence
+\`\`\`
+[Relevant log excerpts]
+\`\`\`
+## Resolution Attempts
+- [Attempt 1] - [Result]
+- [Attempt 2] - [Result]
+## Likely Root Cause
+[Analysis]
+\`\`\`
+## Additional Resources
+- **Diagnostic Reference:** [\`references/diagnostics.md\`](references/diagnostics.md) — detailed commands and log interpretation for each failure mode
+- **Support Bundle Analysis:** [\`references/support-bundle-analysis.md\`](references/support-bundle-analysis.md) — reading a bundle offline: file map, interpretation traps, known gaps
+- **Triage Script:** \`scripts/bundle_triage.py\` — offline first-pass triage, standard library only
+- **Replicated Docs:** [Generating support bundles for Embedded Cluster](https://docs.replicated.com/vendor/support-bundle-embedded)
+## Maintenance
+As new failure modes are discovered in the field, add them to this skill. Update
+\`references/diagnostics.md\` with new patterns and resolution steps, and add the offline equivalent to
+\`references/support-bundle-analysis.md\` when the failure is diagnosable from a bundle.`,category:`integrations`},{name:`openhands-sdk`,description:`Reference skill for the OpenHands Software Agent SDK - the Python framework for building AI agents that write software. Use when you need to build agents with the SDK, create custom tools, configure LLMs, manage conversations, delegate to sub-agents, or deploy agents locally or remotely.`,triggers:[`openhands-sdk`,`openhands sdk`,`software-agent-sdk`,`agent-sdk`,`/sdk`],content:'# OpenHands Software Agent SDK\n\nAll SDK documentation lives at <https://docs.openhands.dev/sdk>.\n\nFor the full topic index, fetch <https://docs.openhands.dev/llms.txt> and read\nthe "OpenHands Software Agent SDK" section.\n\n## Quick reference\n\nInstall: `pip install openhands-sdk openhands-tools`\n\n```python\nimport os\n\nfrom openhands.sdk import LLM, Agent, Conversation, Tool\nfrom openhands.tools.file_editor import FileEditorTool\nfrom openhands.tools.task_tracker import TaskTrackerTool\nfrom openhands.tools.terminal import TerminalTool\n\n\nllm = LLM(\n    model=os.getenv("LLM_MODEL", "gpt-5.5"),\n    api_key=os.getenv("LLM_API_KEY"),\n    base_url=os.getenv("LLM_BASE_URL", None),\n)\n\nagent = Agent(\n    llm=llm,\n    tools=[\n        Tool(name=TerminalTool.name),\n        Tool(name=FileEditorTool.name),\n        Tool(name=TaskTrackerTool.name),\n    ],\n)\n\ncwd = os.getcwd()\nconversation = Conversation(agent=agent, workspace=cwd)\n\nconversation.send_message("Write 3 facts about the current project into FACTS.txt.")\nconversation.run()\nprint("All done!")\n```\n\n## Core classes (`openhands.sdk`)\n\n| Class | Purpose |\n|---|---|\n| [`Agent`](https://docs.openhands.dev/sdk/arch/agent.md) | Reasoning-action loop |\n| [`Condenser`](https://docs.openhands.dev/sdk/arch/condenser.md) | Conversation history compression system |\n| [`Conversation`](https://docs.openhands.dev/sdk/arch/conversation.md) | Conversation orchestration system |\n| [`Event`](https://docs.openhands.dev/sdk/arch/events.md) | Typed event framework |\n| [`LLM`](https://docs.openhands.dev/sdk/arch/llm.md) | Provider-agnostic language model interface |\n| [`SecurityAnalyzer`](https://docs.openhands.dev/sdk/arch/security.md) | Action security analysis and validation |\n| [`Skill`](https://docs.openhands.dev/sdk/arch/skill.md) | Reusable prompt system |\n| [`Tool / ToolDefinition`](https://docs.openhands.dev/sdk/arch/tool-system.md) | Action-observation tool framework |\n| [`Workspace`](https://docs.openhands.dev/sdk/arch/workspace.md) | Execution environment abstraction |\n\n## API reference\n\n[`openhands.sdk.agent`](https://docs.openhands.dev/sdk/api-reference/openhands.sdk.agent.md), [`openhands.sdk.conversation`](https://docs.openhands.dev/sdk/api-reference/openhands.sdk.conversation.md), [`openhands.sdk.event`](https://docs.openhands.dev/sdk/api-reference/openhands.sdk.event.md), [`openhands.sdk.llm`](https://docs.openhands.dev/sdk/api-reference/openhands.sdk.llm.md), [`openhands.sdk.security`](https://docs.openhands.dev/sdk/api-reference/openhands.sdk.security.md), [`openhands.sdk.tool`](https://docs.openhands.dev/sdk/api-reference/openhands.sdk.tool.md), [`openhands.sdk.utils`](https://docs.openhands.dev/sdk/api-reference/openhands.sdk.utils.md), [`openhands.sdk.workspace`](https://docs.openhands.dev/sdk/api-reference/openhands.sdk.workspace.md)\n\n## Guides\n\n- [ACP Agent](https://docs.openhands.dev/sdk/guides/agent-acp.md): Delegate to an ACP-compatible server (Claude Code, Gemini CLI, etc.) instead of calling an LLM directly.\n- [Agent Settings](https://docs.openhands.dev/sdk/guides/agent-settings.md): Configure, serialize, and recreate agents from structured settings.\n- [Agent Skills & Context](https://docs.openhands.dev/sdk/guides/skill.md): Skills add specialized behaviors, domain knowledge, and context-aware triggers to your agent through structured prompts.\n- [API-based Sandbox](https://docs.openhands.dev/sdk/guides/agent-server/api-sandbox.md): Connect to hosted API-based agent server for fully managed infrastructure.\n- [Apptainer Sandbox](https://docs.openhands.dev/sdk/guides/agent-server/apptainer-sandbox.md): Run agent server in rootless Apptainer containers for HPC and shared computing environments.\n- [Ask Agent Questions](https://docs.openhands.dev/sdk/guides/convo-ask-agent.md): Get sidebar replies from the agent during conversation execution without interrupting the main flow.\n- [Assign Reviews](https://docs.openhands.dev/sdk/guides/github-workflows/assign-reviews.md): Automate PR management with intelligent reviewer assignment and workflow notifications using OpenHands Agent\n- [Browser Session Recording](https://docs.openhands.dev/sdk/guides/browser-session-recording.md): Record and replay your agent\'s browser sessions using rrweb.\n- [Browser Use](https://docs.openhands.dev/sdk/guides/agent-browser-use.md): Enable web browsing and interaction capabilities for your agent.\n- [Context Condenser](https://docs.openhands.dev/sdk/guides/context-condenser.md): Manage agent memory by condensing conversation history to save tokens.\n- [Conversation Goals](https://docs.openhands.dev/sdk/guides/agent-server/conversation-goals.md): Add a resumable goal strategy to a normal agent-server conversation.\n- [Conversation with Async](https://docs.openhands.dev/sdk/guides/convo-async.md): Use async/await for concurrent agent operations and non-blocking execution.\n- [Creating Custom Agent](https://docs.openhands.dev/sdk/guides/agent-custom.md): Learn how to design specialized agents with custom tool sets\n- [Critic (Experimental)](https://docs.openhands.dev/sdk/guides/critic.md): Real-time evaluation of agent actions using an LLM-based critic model, with built-in iterative refinement.\n- [Custom Tools](https://docs.openhands.dev/sdk/guides/custom-tools.md): Tools define what agents can do. The SDK includes built-in tools for common operations and supports creating custom tools for specialized needs.\n- [Custom Tools with Remote Agent Server](https://docs.openhands.dev/sdk/guides/agent-server/custom-tools.md): Learn how to use custom tools with a remote agent server by building a custom base image that includes your tool implementations.\n- [Custom Visualizer](https://docs.openhands.dev/sdk/guides/convo-custom-visualizer.md): Customize conversation visualization by creating custom visualizers or configuring the default visualizer.\n- [Deferred Init (Warm-Pool)](https://docs.openhands.dev/sdk/guides/agent-server/deferred-init.md): Pre-warm agent-server pods before a user is matched, then activate them at runtime with POST /api/init.\n- [Docker Sandbox](https://docs.openhands.dev/sdk/guides/agent-server/docker-sandbox.md): Run agent server in isolated Docker containers for security and reproducibility.\n- [Exception Handling](https://docs.openhands.dev/sdk/guides/llm-error-handling.md): Provider‑agnostic exceptions raised by the SDK and recommended patterns for handling them.\n- [FAQ](https://docs.openhands.dev/sdk/faq.md): Frequently asked questions about the OpenHands SDK\n- [File-Based Agents](https://docs.openhands.dev/sdk/guides/agent-file-based.md): Define specialized sub-agents as simple Markdown files with YAML frontmatter — no Python code required.\n- [Fork a Conversation](https://docs.openhands.dev/sdk/guides/convo-fork.md): Branch off an existing conversation for follow-up exploration without contaminating the original.\n- [Getting Started](https://docs.openhands.dev/sdk/getting-started.md): Install the OpenHands SDK and build AI agents that write software.\n- [Goal Completion Loop](https://docs.openhands.dev/sdk/guides/convo-goal.md): Drive a conversation toward a verifiable objective with a judge-driven, self-continuing completion loop.\n- [GPT-5 Preset (ApplyPatchTool)](https://docs.openhands.dev/sdk/guides/llm-gpt5-preset.md): Use the GPT-5 preset to build an agent that swaps the standard FileEditorTool for ApplyPatchTool.\n- [Hello World](https://docs.openhands.dev/sdk/guides/hello-world.md): The simplest possible OpenHands agent - configure an LLM, create an agent, and complete a task.\n- [Hooks](https://docs.openhands.dev/sdk/guides/hooks.md): Use lifecycle hooks to observe, log, and customize agent execution.\n- [Image Input](https://docs.openhands.dev/sdk/guides/llm-image-input.md): Send images to multimodal agents for vision-based tasks and analysis.\n- [Interactive Terminal](https://docs.openhands.dev/sdk/guides/agent-interactive-terminal.md): Enable agents to interact with terminal applications like ipython, python REPL, and other interactive CLI tools.\n- [Iterative Refinement](https://docs.openhands.dev/sdk/guides/iterative-refinement.md): Implement iterative refinement workflows where agents refine their work based on critique feedback until quality thresholds are met.\n- [LLM Fallback Strategy](https://docs.openhands.dev/sdk/guides/llm-fallback.md): Automatically try alternate LLMs when the primary model fails with a transient error.\n- [LLM Profile Store](https://docs.openhands.dev/sdk/guides/llm-profile-store.md): Save, load, and manage reusable LLM configurations so you never repeat setup code again.\n- [LLM Registry](https://docs.openhands.dev/sdk/guides/llm-registry.md): Dynamically select and configure language models using the LLM registry.\n- [LLM Streaming](https://docs.openhands.dev/sdk/guides/llm-streaming.md): Stream LLM responses token-by-token for real-time display and interactive user experiences.\n- [LLM Subscriptions](https://docs.openhands.dev/sdk/guides/llm-subscriptions.md): Use your ChatGPT Plus/Pro subscription to access Codex models without consuming API credits.\n- [Local Agent Server](https://docs.openhands.dev/sdk/guides/agent-server/local-server.md): Install and run an OpenHands Agent Server on your machine, then connect to it from the SDK.\n- [Metrics Tracking](https://docs.openhands.dev/sdk/guides/metrics.md): Track token usage, costs, and latency metrics for your agents.\n- [Model Context Protocol](https://docs.openhands.dev/sdk/guides/mcp.md): Model Context Protocol (MCP) enables dynamic tool integration from external servers. Agents can discover and use MCP-provided tools automatically.\n- [Model Routing](https://docs.openhands.dev/sdk/guides/llm-routing.md): Route agent\'s LLM requests to different models.\n- [Observability & Tracing](https://docs.openhands.dev/sdk/guides/observability.md): Enable OpenTelemetry tracing to monitor and debug your agent\'s execution with tools like Laminar, MLflow, Honeycomb, or any OTLP-compatible backend.\n- [OpenAI-Compatible Endpoint](https://docs.openhands.dev/sdk/guides/agent-server/openai-gateway.md): Call an OpenHands agent-server through the OpenAI Chat Completions protocol.\n- [OpenHands Cloud Workspace](https://docs.openhands.dev/sdk/guides/agent-server/cloud-workspace.md): Connect to OpenHands Cloud for fully managed sandbox environments with optional SaaS credential inheritance.\n- [Overview](https://docs.openhands.dev/sdk/guides/agent-server/overview.md): Run agents on remote servers with isolated workspaces for production deployments.\n- [Parallel Tool Execution](https://docs.openhands.dev/sdk/guides/parallel-tool-execution.md): Execute multiple tools concurrently within a single LLM response to improve throughput for independent operations.\n- [Pause and Resume](https://docs.openhands.dev/sdk/guides/convo-pause-and-resume.md): Pause agent execution, perform operations, and resume without losing state.\n- [Persistence](https://docs.openhands.dev/sdk/guides/convo-persistence.md): Save and restore conversation state for multi-session workflows.\n- [Persistent Memory](https://docs.openhands.dev/sdk/guides/persistent-memory.md): Give agents opt-in, two-tier memory that survives across conversations.\n- [Plugins](https://docs.openhands.dev/sdk/guides/plugins.md): Plugins bundle skills, hooks, MCP servers, agents, and commands into reusable packages that extend agent capabilities.\n- [PR Review](https://docs.openhands.dev/sdk/guides/github-workflows/pr-review.md): Use OpenHands Agent to generate meaningful pull request review\n- [Reasoning](https://docs.openhands.dev/sdk/guides/llm-reasoning.md): Access model reasoning traces from Anthropic extended thinking and OpenAI responses API.\n- [Secret Registry](https://docs.openhands.dev/sdk/guides/secrets.md): Provide environment variables and secrets to agent workspace securely.\n- [Security & Action Confirmation](https://docs.openhands.dev/sdk/guides/security.md): Control agent action execution through confirmation policy and security analyzer.\n- [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.\n- [Software Agent SDK](https://docs.openhands.dev/sdk.md): Build AI agents that write software. A clean, modular SDK with production-ready tools.\n- [Stuck Detector](https://docs.openhands.dev/sdk/guides/agent-stuck-detector.md): Detect and handle stuck agents automatically with timeout mechanisms.\n- [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.\n- [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.\n- [TODO Management](https://docs.openhands.dev/sdk/guides/github-workflows/todo-management.md): Implement TODOs using OpenHands Agent\n\n## Examples\n\nSource: [`examples/`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples)\n\n### [`01_standalone_sdk/`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk)\n\n- [`01_hello_world.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/01_hello_world.py)\n- [`02_custom_tools.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/02_custom_tools.py)\n- [`03_activate_skill.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/03_activate_skill.py)\n- [`04_confirmation_mode_example.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/04_confirmation_mode_example.py)\n- [`05_use_llm_registry.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/05_use_llm_registry.py)\n- [`06_interactive_terminal_w_reasoning.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/06_interactive_terminal_w_reasoning.py)\n- [`07_mcp_integration.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/07_mcp_integration.py)\n- [`08_mcp_with_oauth.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/08_mcp_with_oauth.py)\n- [`09_pause_example.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/09_pause_example.py)\n- [`10_persistence.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/10_persistence.py)\n- [`11_async.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/11_async.py)\n- [`12_custom_secrets.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/12_custom_secrets.py)\n- [`13_get_llm_metrics.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/13_get_llm_metrics.py)\n- [`14_context_condenser.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/14_context_condenser.py)\n- [`15_browser_use.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/15_browser_use.py)\n- [`16_llm_security_analyzer.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/16_llm_security_analyzer.py)\n- [`17_image_input.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/17_image_input.py)\n- [`18_send_message_while_processing.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/18_send_message_while_processing.py)\n- [`19_llm_routing.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/19_llm_routing.py)\n- [`20_stuck_detector.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/20_stuck_detector.py)\n- [`21_generate_extraneous_conversation_costs.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/21_generate_extraneous_conversation_costs.py)\n- [`22_anthropic_thinking.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/22_anthropic_thinking.py)\n- [`23_responses_reasoning.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/23_responses_reasoning.py)\n- [`24_planning_agent_workflow.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/24_planning_agent_workflow.py)\n- [`25_agent_delegation.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/25_agent_delegation.py)\n- [`26_custom_visualizer.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/26_custom_visualizer.py)\n- [`27_observability_laminar.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/27_observability_laminar.py)\n- [`28_ask_agent_example.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/28_ask_agent_example.py)\n- [`29_llm_streaming.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/29_llm_streaming.py)\n- [`30_tom_agent.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/30_tom_agent.py)\n- [`31_iterative_refinement.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/31_iterative_refinement.py)\n- [`32_configurable_security_policy.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/32_configurable_security_policy.py)\n- [`33_hooks`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk/33_hooks)\n- [`34_critic_example.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/34_critic_example.py)\n- [`35_subscription_login.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/35_subscription_login.py)\n- [`36_event_json_to_openai_messages.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/36_event_json_to_openai_messages.py)\n- [`37_llm_profile_store`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk/37_llm_profile_store)\n- [`38_browser_session_recording.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/38_browser_session_recording.py)\n- [`39_llm_fallback.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/39_llm_fallback.py)\n- [`40_acp_agent_example.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/40_acp_agent_example.py)\n- [`41_task_tool_set.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/41_task_tool_set.py)\n- [`42_file_based_subagents.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/42_file_based_subagents.py)\n- [`44_model_switching_in_convo.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/44_model_switching_in_convo.py)\n- [`45_parallel_tool_execution.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/45_parallel_tool_execution.py)\n- [`46_agent_settings.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/46_agent_settings.py)\n- [`47_defense_in_depth_security.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/47_defense_in_depth_security.py)\n- [`48_conversation_fork.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/48_conversation_fork.py)\n- [`49_switch_llm_tool.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/49_switch_llm_tool.py)\n- [`50_async_cancellation.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/50_async_cancellation.py)\n- [`51_agent_hooks`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk/51_agent_hooks)\n- [`52_dynamic_workflow.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/52_dynamic_workflow.py)\n- [`53_client_defined_tools.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/53_client_defined_tools.py)\n- [`54_goal_completion_loop.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/54_goal_completion_loop.py)\n- [`55_persistent_memory.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/55_persistent_memory.py)\n- [`56_structured_output.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/56_structured_output.py)\n- [`57_prompt_hooks`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk/57_prompt_hooks)\n- [`58_ask_oracle_tool`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk/58_ask_oracle_tool)\n\n### [`02_remote_agent_server/`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/02_remote_agent_server)\n\n- [`01_convo_with_local_agent_server.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/01_convo_with_local_agent_server.py)\n- [`02_convo_with_docker_sandboxed_server.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/02_convo_with_docker_sandboxed_server.py)\n- [`03_browser_use_with_docker_sandboxed_server.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/03_browser_use_with_docker_sandboxed_server.py)\n- [`04_convo_with_api_sandboxed_server.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/04_convo_with_api_sandboxed_server.py)\n- [`05_vscode_with_docker_sandboxed_server.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/05_vscode_with_docker_sandboxed_server.py)\n- [`06_custom_tool`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/02_remote_agent_server/06_custom_tool)\n- [`07_convo_with_cloud_workspace.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/07_convo_with_cloud_workspace.py)\n- [`08_convo_with_apptainer_sandboxed_server.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/08_convo_with_apptainer_sandboxed_server.py)\n- [`09_acp_agent_with_remote_runtime.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/09_acp_agent_with_remote_runtime.py)\n- [`10_cloud_workspace_share_credentials.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/10_cloud_workspace_share_credentials.py)\n- [`11_conversation_fork.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/11_conversation_fork.py)\n- [`12_settings_and_secrets_api.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/12_settings_and_secrets_api.py)\n- [`13_workspace_get_llm.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/13_workspace_get_llm.py)\n- [`14_client_defined_tools.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/14_client_defined_tools.py)\n- [`15_openai_compatible_gateway.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/15_openai_compatible_gateway.py)\n- [`16_deferred_init.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/16_deferred_init.py)\n- [`17_convo_with_agent_sandbox_server.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/02_remote_agent_server/17_convo_with_agent_sandbox_server.py)\n- [`agent_sandbox_deploy`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/02_remote_agent_server/agent_sandbox_deploy)\n- [`hook_scripts`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/02_remote_agent_server/hook_scripts)\n- [`scripts`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/02_remote_agent_server/scripts)\n\n### [`03_github_workflows/`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows)\n\n- [`01_basic_action`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/01_basic_action)\n- [`02_pr_review`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/02_pr_review)\n- [`03_todo_management`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/03_todo_management)\n- [`04_datadog_debugging`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/04_datadog_debugging)\n- [`05_posthog_debugging`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/05_posthog_debugging)\n\n### [`04_llm_specific_tools/`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/04_llm_specific_tools)\n\n- [`01_gpt5_apply_patch_preset.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/04_llm_specific_tools/01_gpt5_apply_patch_preset.py)\n- [`02_gemini_file_tools.py`](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/04_llm_specific_tools/02_gemini_file_tools.py)\n\n### [`05_skills_and_plugins/`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/05_skills_and_plugins)\n\n- [`01_loading_agentskills`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/05_skills_and_plugins/01_loading_agentskills)\n- [`02_loading_plugins`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/05_skills_and_plugins/02_loading_plugins)\n- [`03_managing_installed_skills`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/05_skills_and_plugins/03_managing_installed_skills)\n- [`04_mixed_marketplace_skills`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/05_skills_and_plugins/04_mixed_marketplace_skills)',category:`agent-authoring`,defaultEnabled:!0},{name:`pdflatex`,description:`Install and use pdflatex to compile LaTeX documents into PDFs on Linux. Use when generating academic papers, research publications, or any documents written in LaTeX.`,triggers:[`pdflatex`],content:`PdfLatex is a tool that converts Latex sources into PDF. This is specifically very important for researchers, as they use it to publish their findings. It could be installed very easily using Linux terminal, though this seems an annoying task on Windows. Installation commands are given below.
 * Install the TexLive base