@openhands/extensions 0.5.0 → 0.7.0

package/skills/agent-canvas-environment/README.md

@@ -0,0 +1,5 @@
+# agent-canvas-environment
+
+Guidance for working inside a local Agent Canvas environment, including local agent-server auth, safe workspace hygiene, and delegation to new local conversations.
+
+See: [SKILL.md](./SKILL.md)

package/skills/agent-canvas-environment/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: agent-canvas-environment
+description: Work effectively inside a local Agent Canvas environment, including local agent-server auth, frontend/backend port discovery, safe workspace hygiene, and delegating work to a new local conversation through POST /api/conversations.
+triggers:
+- agent canvas
+- agent-canvas
+- local conversation
+- delegate local conversation
+- session api key
+- X-Session-API-Key
+- localhost:8001
+---
+
+# Agent Canvas Environment
+
+Use this skill when running inside or alongside a local Agent Canvas stack, especially when the user asks to inspect the local backend, create or monitor local conversations, or delegate work to another local conversation.
+
+## Core rules
+
+- Treat the local Agent Canvas backend as an agent-server API, usually `http://localhost:8001`.
+- Treat the local UI as a separate frontend, usually `http://localhost:8000`.
+- Do not print session API keys. Pass them directly in `X-Session-API-Key`.
+- Trust any runtime-services block or explicit user-provided host over default ports.
+- Before mutating a repository, check `git status -sb`. If a worktree has unrelated changes, use a separate worktree or clone.
+- When delegating, write a self-contained prompt. The new conversation does not inherit the current chat context.
+
+## Find the session key
+
+Use the first available value, without echoing it:
+
+```bash
+KEY="${SESSION_API_KEY:-${OH_SESSION_API_KEYS_0:-${LOCAL_BACKEND_API_KEY:-}}}"
+if [ -z "$KEY" ] && [ -f "$HOME/.openhands/agent-canvas/api-key.txt" ]; then
+  KEY="$(tr -d '\n' < "$HOME/.openhands/agent-canvas/api-key.txt")"
+fi
+test -n "$KEY" || { echo "No Agent Canvas session API key found" >&2; exit 1; }
+```
+
+Validate backend access:
+
+```bash
+curl -sS -o /tmp/agent-canvas-conversations.json -w '%{http_code}\n' \
+  -H "X-Session-API-Key: $KEY" \
+  http://localhost:8001/api/conversations/search
+```
+
+HTTP `200` means the backend and key work.
+
+## Delegate to a local conversation
+
+Use `POST /api/conversations` with:
+
+- the **encrypted** `agent_settings` from `GET /api/settings` (with `X-Expose-Secrets: encrypted`), which carries the real Fernet-encrypted `llm.api_key`, the existing `agent_context`, and the agent kind — so you never handle plaintext credentials and you don't drop the caller's skill/context config
+- `secrets_encrypted: true` so the agent-server decrypts that `api_key` server-side
+- the exec tool set merged into `agent_settings.tools` (and `task_tool_set` when you enable sub-agents)
+- `tool_module_qualnames` for any non-SDK tools (e.g. `canvas_ui`)
+- `agent_context.load_public_skills`/`load_user_skills`/`load_project_skills` set to `true` if the delegated agent should inherit bundled/user/project skills
+- a fresh absolute workspace directory
+- `initial_message.run: true`
+- `worktree: false` when the workspace is already isolated
+
+### Credential handling — important
+
+`GET /api/settings` (default) **masks** every credential — `llm.api_key` comes back as the literal string `"**********"`. If you forward that verbatim, the new conversation authenticates with the placeholder and fails immediately with `LLMAuthenticationError` (`You must provide an API key`).
+
+The supported way to obtain forwardable credentials is the **`X-Expose-Secrets: encrypted`** request header. With it, `/api/settings` returns the real `llm.api_key` as a **Fernet-encrypted token** (starts with `gAAAAA`) intended to be sent back to the server with `secrets_encrypted: true`; the agent-server's `decrypt_incoming_llm_secrets` decrypts it server-side. Do **not** read `~/.openhands/profiles/*.json` directly — that is brittle (the caller may not share the backend's home directory, `active_profile` may be null, the profile store may live elsewhere).
+
+Two working approaches:
+
+1. **`agent_profile_id` (simplest, but no tools)** — send only `agent_profile_id: "<uuid>"` (from `GET /api/agent-profiles` → the profile whose `id` equals `active_agent_profile_id` from `/api/settings`). The server resolves the LLM key + agent kind from the profile. Mutually exclusive with `agent`/`agent_settings`, and the `openhands` agent-profile schema forbids `tools`/`include_default_tools`, so the conversation gets **zero exec tools** this way. Use only when the task needs no tools.
+
+2. **Encrypted `agent_settings` (full tools, preserves context)** — start from the encrypted `/api/settings` `agent_settings` payload, drop `schema_version` and `mcp_config` (to avoid MCP-connection failures at creation time), merge in the exec tool set and `load_*_skills` flags, and send with `secrets_encrypted: true`. This is the pattern for real delegated work.
+
+Template (full tools, preserves context):
+
+```bash
+set -euo pipefail
+
+BASE="${AGENT_CANVAS_BACKEND:-http://localhost:8001}"
+KEY="${SESSION_API_KEY:-${OH_SESSION_API_KEYS_0:-${LOCAL_BACKEND_API_KEY:-}}}"
+if [ -z "$KEY" ] && [ -f "$HOME/.openhands/agent-canvas/api-key.txt" ]; then
+  KEY="$(tr -d '\n' < "$HOME/.openhands/agent-canvas/api-key.txt")"
+fi
+test -n "$KEY" || { echo "No Agent Canvas session API key found" >&2; exit 1; }
+
+WORKDIR="${WORKDIR:-$HOME/workspace/delegated/$(date +%Y%m%d-%H%M%S)}"
+mkdir -p "$WORKDIR"
+
+# Fetch the agent_settings with ENCRYPTED secrets exposed. This returns the
+# real llm.api_key as a Fernet token (gAAAAA...) plus the existing
+# agent_context/agent kind, so we preserve the caller's config and never
+# handle plaintext credentials.
+SETTINGS_JSON="$(curl -sS -H "X-Session-API-Key: $KEY" -H "X-Expose-Secrets: encrypted" "$BASE/api/settings")"
+
+PROMPT='Write a complete, task-specific prompt here. Include repo, branch, constraints, validation, and expected report.'
+
+PAYLOAD="$(jq -n --argjson settings "$SETTINGS_JSON" --arg prompt "$PROMPT" --arg workdir "$WORKDIR" '
+  # Start from the encrypted agent_settings so llm.api_key (Fernet token),
+  # agent_kind, and agent_context are preserved. Drop schema_version and
+  # mcp_config (MCP servers can fail to connect at creation time; the profile
+  # can be re-resolved later if needed).
+  def base_agent_settings:
+    ($settings.agent_settings // {})
+    | del(.schema_version)
+    | del(.mcp_config);
+
+  # Merge the exec tool set into the existing tools list. Include task_tool_set
+  # when sub-agents are enabled — enable_sub_agents alone does not expose the
+  # delegation tool; Agent Canvas adds task_tool_set for that.
+  def with_tools:
+    .tools = ((.tools // []) + [
+      {name: "terminal", params: {}},
+      {name: "file_editor", params: {}},
+      {name: "task_tracker", params: {}},
+      {name: "browser_tool_set", params: {}},
+      {name: "canvas_ui", params: {}}
+    ] + (if .enable_sub_agents then [{name: "task_tool_set", params: {}}] else [] end)
+    | unique_by(.name));
+
+  # Preserve the existing agent_context and enable skill loading for the
+  # delegated agent (defaults are false, so set these explicitly).
+  def with_skill_loading:
+    .agent_context = ((.agent_context // {}) + {
+      load_public_skills: true,
+      load_user_skills: true,
+      load_project_skills: true
+    });
+
+  ($settings.conversation_settings // {}) as $conv |
+  {
+    secrets_encrypted: true,
+    agent_settings: (base_agent_settings | with_tools | with_skill_loading),
+    tool_module_qualnames: { canvas_ui: "canvas_ui_tool" },
+    workspace: {kind: "LocalWorkspace", working_dir: $workdir},
+    confirmation_policy: {kind: "NeverConfirm"},
+    # Delegated tasks usually need more than the SDK default of 80 iterations;
+    # default to the caller's conversation_settings value (1000 in Agent Canvas)
+    # so long-running tasks aren't cut off prematurely. Override per-task if needed.
+    max_iterations: (($conv.max_iterations // 1000) | if . == null then 1000 else . end),
+    stuck_detection: true,
+    autotitle: true,
+    worktree: false,
+    initial_message: {
+      role: "user",
+      content: [{type: "text", text: $prompt}],
+      run: true
+    }
+  }
+')"
+
+curl -sS -X POST "$BASE/api/conversations" \
+  -H "Content-Type: application/json" \
+  -H "X-Session-API-Key: $KEY" \
+  --data-binary "$PAYLOAD" | jq '{id, title, execution_status, workspace}'
+```
+
+Verify the new conversation actually has tools and is running (not errored):
+
+```bash
+CID="<conversation_id>"
+curl -sS -H "X-Session-API-Key: $KEY" "$BASE/api/conversations/$CID" \
+  | jq '{execution_status, tools: [.agent.tools[]?.name]}'
+curl -sS -H "X-Session-API-Key: $KEY" "$BASE/api/conversations/$CID/events/search?limit=20" \
+  | jq '[.events[]? | select(.kind=="ConversationErrorEvent") | .code] // []'
+```
+
+`execution_status` should be `running`/`idle`/`finished` (not `error`), `tools` should list the exec tools, and there should be no `ConversationErrorEvent`.
+
+If MCP servers configured in the profile are unreachable, conversation creation can fail with `MCP Connection Failure`; the template drops `mcp_config` from the forwarded `agent_settings` to avoid that.
+
+Report both links:
+
+- UI: `http://localhost:8000/conversations/<conversation_id>`
+- API: `http://localhost:8001/api/conversations/<conversation_id>`
+
+## Monitor a delegated conversation
+
+```bash
+CID="<conversation_id>"
+curl -sS -H "X-Session-API-Key: $KEY" "$BASE/api/conversations/$CID" \
+  | jq '{id, title, execution_status, updated_at, workspace, agent_kind: .agent.kind, current_model_id, current_model_name}'
+
+curl -sS -H "X-Session-API-Key: $KEY" "$BASE/api/conversations/$CID/events/search?limit=20" \
+  | jq '.events // .items // .'
+```
+
+Terminal statuses commonly include `idle`, `running`, `finished`, `error`, `stuck`, and `stopped`.
+
+## Prompt checklist for delegation
+
+Include:
+
+- repository owner/name and local path if relevant
+- branch, PR, issue, or Linear ticket identifiers
+- current status and known blockers
+- exact files or subsystems in scope
+- dirty-worktree warnings and paths not to touch
+- whether to push, open a PR, or only report
+- checks/tests to run
+- expected final report format
+
+Do not rely on the new conversation knowing anything from the current thread.

package/skills/bitbucket/README.md

@@ -1,6 +1,7 @@
 # Bitbucket
 
-Interact with Bitbucket repositories and pull requests using the BITBUCKET_TOKEN environment variable. Use when working with code hosted on Bitbucket or managing Bitbucket resources via API.
+Bitbucket integration **hub** skill. It detects whether the repository is on Bitbucket
+Cloud or Bitbucket Data Center and directs the agent to the matching detailed skill.
 
 ## Triggers
 
@@ -9,42 +10,24 @@ This skill is activated by the following keywords:
 - `bitbucket`
 - `git`
 
-## Details
-
-You have access to an environment variable, `BITBUCKET_TOKEN`, which allows you to interact with
-the Bitbucket API.
-
-<IMPORTANT>
-You can use `curl` with the `BITBUCKET_TOKEN` to interact with Bitbucket's API.
-ALWAYS use the Bitbucket API for operations instead of a web browser.
-ALWAYS use the `create_bitbucket_pr` tool to open a pull request
-</IMPORTANT>
-
-Only rewrite the Bitbucket remote if a push actually fails with authentication errors and the user has asked you to push. Do not proactively rewrite `origin`. OpenHands commonly stores `BITBUCKET_TOKEN` in the same unencoded `user:token` form used by commands such as `curl --user "$BITBUCKET_TOKEN" ...`, so keep it in that form unless you truly need to embed it in a Git remote URL.
-
-If you need a non-interactive HTTPS remote URL, split `BITBUCKET_TOKEN` on the first `:` and URL-encode each part before calling `git remote set-url`. This avoids breaking usernames or emails that contain reserved URL characters such as `@`:
-
-```bash
-BB_USER="${BITBUCKET_TOKEN%%:*}" && \
-BB_PASS="${BITBUCKET_TOKEN#*:}" && \
-ENCODED_USER=$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$BB_USER") && \
-ENCODED_PASS=$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$BB_PASS") && \
-git remote set-url origin "https://${ENCODED_USER}:${ENCODED_PASS}@bitbucket.org/username/repo.git"
-```
-
-Atlassian's Bitbucket Cloud docs recommend avoiding long-lived credentials in the remote URL when possible. Their API token examples use either `https://{bitbucket_username}:{api_token}@...` or `https://x-bitbucket-api-token-auth:{api_token}@...`; OpenHands users should only construct those URLs on demand, with proper URL encoding.
-
-Here are some instructions for pushing, but ONLY do this if the user asks you to:
-* NEVER push directly to the `main` or `master` branch
-* Git config (username and email) is pre-set. Do not modify.
-* You may already be on a branch starting with `openhands-workspace`. Create a new branch with a better name before pushing.
-* Use the `create_bitbucket_pr` tool to create a pull request, if you haven't already
-* Once you've created your own branch or a pull 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.
-* Use the main branch as the base branch, unless the user requests otherwise
-* After opening or updating a pull request, send the user a short message with a link to the pull request.
-* Do NOT mark a pull request as ready to review unless the user explicitly says so
-* 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:
-```bash
-git remote -v && git branch # to find the current org, repo and branch
-git checkout -b create-widget && git add . && git commit -m "Create widget" && git push -u origin create-widget
-```
+## Why a hub skill?
+
+Bitbucket ships as two products that behave differently — **Bitbucket Cloud**
+(`bitbucket.org`) and **Bitbucket Data Center** (self-hosted Bitbucket Server). They use
+different token environment variables, REST APIs, repository identifiers, git remote URL
+formats, and pull request tools.
+
+This hub triggers broadly (on `git`/`bitbucket`) so it loads for any Bitbucket task — even
+when the words "data center" never appear. It then:
+
+1. **Detects** the environment by checking which token variable is present
+   (`BITBUCKET_DATA_CENTER_TOKEN` → Data Center, else `BITBUCKET_TOKEN` → Cloud). The check
+   is case-insensitive so it is robust to env-var casing differences.
+2. **Hands off** to the matching detailed skill via the `invoke_skill` tool:
+   - Bitbucket Cloud → [`bitbucket-cloud`](../bitbucket-cloud/)
+   - Bitbucket Data Center → [`bitbucket-data-center`](../bitbucket-data-center/)
+
+The hub also carries a small quick-reference table as a fallback in case the detailed skill
+cannot be loaded.
+
+See [`SKILL.md`](SKILL.md) for the full content.

package/skills/bitbucket/SKILL.md

@@ -1,45 +1,57 @@
 ---
 name: bitbucket
-description: Interact with Bitbucket repositories and pull requests using the BITBUCKET_TOKEN environment variable. Use when working with code hosted on Bitbucket or managing Bitbucket resources via API.
+description: Bitbucket integration hub. Detects whether the repository is on Bitbucket Cloud or Bitbucket Data Center and directs you to the matching detailed skill (bitbucket-cloud or bitbucket-data-center). Use for any Bitbucket repository or pull request task.
 triggers:
 - bitbucket
 - git
 ---
 
-You have access to an environment variable, `BITBUCKET_TOKEN`, which allows you to interact with
-the Bitbucket API.
+You are working with **Bitbucket**, which ships as two distinct products that behave
+differently:
 
-<IMPORTANT>
-You can use `curl` with the `BITBUCKET_TOKEN` to interact with Bitbucket's API.
-ALWAYS use the Bitbucket API for operations instead of a web browser.
-ALWAYS use the `create_bitbucket_pr` tool to open a pull request
-</IMPORTANT>
+- **Bitbucket Cloud** (`bitbucket.org`) — authenticates with the `BITBUCKET_TOKEN`
+  environment variable.
+- **Bitbucket Data Center** (self-hosted Bitbucket Server) — authenticates with the
+  `BITBUCKET_DATA_CENTER_TOKEN` environment variable.
 
-Only rewrite the Bitbucket remote if a push actually fails with authentication errors and the user has asked you to push. Do not proactively rewrite `origin`. OpenHands OSS commonly stores `BITBUCKET_TOKEN` in the same unencoded `user:token` form used by commands such as `curl --user "$BITBUCKET_TOKEN" ...`, so keep it in that form unless you truly need to embed it in a Git remote URL.
+They use different REST APIs, repository identifiers, git remote URL formats, and pull
+request tools, so you must first determine which one you are on, then load the matching
+detailed skill for full instructions.
 
-If you need a non-interactive HTTPS remote URL, split `BITBUCKET_TOKEN` on the first `:` and URL-encode each part before calling `git remote set-url`. This avoids breaking usernames or emails that contain reserved URL characters such as `@`:
+## Step 1 — Detect which Bitbucket you are on
+
+Check which token environment variable is present. Environment variable names are
+case-sensitive, so look for it case-insensitively:
 
 ```bash
-BB_USER="${BITBUCKET_TOKEN%%:*}" && \
-BB_PASS="${BITBUCKET_TOKEN#*:}" && \
-ENCODED_USER=$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$BB_USER") && \
-ENCODED_PASS=$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$BB_PASS") && \
-git remote set-url origin "https://${ENCODED_USER}:${ENCODED_PASS}@bitbucket.org/username/repo.git"
+env | grep -i 'bitbucket' || echo "no bitbucket token found"
 ```
 
-Atlassian's Bitbucket Cloud docs recommend avoiding long-lived credentials in the remote URL when possible. Their API token examples use either `https://{bitbucket_username}:{api_token}@...` or `https://x-bitbucket-api-token-auth:{api_token}@...`; OpenHands users should only construct those URLs on demand, with proper URL encoding.
-
-Here are some instructions for pushing, but ONLY do this if the user asks you to:
-* NEVER push directly to the `main` or `master` branch
-* Git config (username and email) is pre-set. Do not modify.
-* You may already be on a branch starting with `openhands-workspace`. Create a new branch with a better name before pushing.
-* Use the `create_bitbucket_pr` tool to create a pull request, if you haven't already
-* Once you've created your own branch or a pull 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.
-* Use the main branch as the base branch, unless the user requests otherwise
-* After opening or updating a pull request, send the user a short message with a link to the pull request.
-* Do NOT mark a pull request as ready to review unless the user explicitly says so
-* 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:
-```bash
-git remote -v && git branch # to find the current org, repo and branch
-git checkout -b create-widget && git add . && git commit -m "Create widget" && git push -u origin create-widget
-```
+- If a **`BITBUCKET_DATA_CENTER_TOKEN`** variable is set (in any letter case) → you are on
+  **Bitbucket Data Center**.
+- Otherwise, if a **`BITBUCKET_TOKEN`** variable is set → you are on **Bitbucket Cloud**.
+- If neither is set, ask the user how they authenticate to Bitbucket before proceeding.
+
+When you reference the token later, use the exact variable name (and letter case) that
+actually exists in the environment.
+
+## Step 2 — Load the detailed skill
+
+Once you know the environment, use the `invoke_skill` tool to load the matching skill for
+full instructions on API calls, authenticated git remotes, and opening pull requests:
+
+- Bitbucket Cloud → invoke the **`bitbucket-cloud`** skill.
+- Bitbucket Data Center → invoke the **`bitbucket-data-center`** skill.
+
+## Quick reference (fallback)
+
+If you are unable to load the detailed skill, these are the essentials. Always use the
+Bitbucket API (not a web browser) and always use the listed PR tool to open a pull request.
+
+| | Bitbucket Cloud | Bitbucket Data Center |
+|---|---|---|
+| Token env var | `BITBUCKET_TOKEN` | `BITBUCKET_DATA_CENTER_TOKEN` |
+| Host | `bitbucket.org` | self-hosted domain |
+| REST API base | `https://api.bitbucket.org/2.0` | `https://<host>/rest/api/1.0` |
+| Repository identifier | `workspace/repo_slug` | `PROJECT/repo_slug` (project key) |
+| Pull request tool | `create_bitbucket_pr` | `create_bitbucket_data_center_pr` |

package/skills/bitbucket-cloud/.plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "bitbucket-cloud",
+  "version": "1.0.0",
+  "description": "Bitbucket Cloud (bitbucket.org) specifics — authenticate with BITBUCKET_TOKEN, use the REST API v2, workspace/repo_slug repositories, and the create_bitbucket_pr tool. Loaded on demand by the bitbucket skill once a Cloud environment is detected.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "bitbucket",
+    "bitbucket-cloud",
+    "git",
+    "pull-request"
+  ]
+}

package/skills/bitbucket-cloud/README.md

@@ -0,0 +1,15 @@
+# Bitbucket Cloud
+
+Bitbucket Cloud (`bitbucket.org`) specifics — `BITBUCKET_TOKEN` auth, REST API v2,
+`workspace/repo_slug` repositories, and the `create_bitbucket_pr` tool.
+
+## Triggers
+
+This skill has no auto-injection triggers. It is **invoke-only**: it is loaded on demand
+via the `invoke_skill` tool, normally by the [`bitbucket`](../bitbucket/) hub skill after
+it detects a Bitbucket Cloud environment (i.e. `BITBUCKET_TOKEN` is set).
+
+## Details
+
+See [`SKILL.md`](SKILL.md) for the full content, including authenticated git remote
+construction and pull request instructions.

package/skills/bitbucket-cloud/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: bitbucket-cloud
+description: Bitbucket Cloud (bitbucket.org) specifics — authenticate with BITBUCKET_TOKEN, use the REST API v2, workspace/repo_slug repositories, and the create_bitbucket_pr tool. Loaded on demand by the bitbucket skill once a Cloud environment is detected.
+---
+
+You are working with **Bitbucket Cloud** (`bitbucket.org`). You have access to an
+environment variable, `BITBUCKET_TOKEN`, which allows you to interact with the Bitbucket
+Cloud API.
+
+- REST API base URL: `https://api.bitbucket.org/2.0`
+- Repository identifier format: `workspace/repo_slug`
+
+<IMPORTANT>
+You can use `curl` with the `BITBUCKET_TOKEN` to interact with Bitbucket's API.
+ALWAYS use the Bitbucket API for operations instead of a web browser.
+ALWAYS use the `create_bitbucket_pr` tool to open a pull request
+</IMPORTANT>
+
+Only rewrite the Bitbucket remote if a push actually fails with authentication errors and the user has asked you to push. Do not proactively rewrite `origin`. OpenHands OSS commonly stores `BITBUCKET_TOKEN` in the same unencoded `user:token` form used by commands such as `curl --user "$BITBUCKET_TOKEN" ...`, so keep it in that form unless you truly need to embed it in a Git remote URL.
+
+If you need a non-interactive HTTPS remote URL, split `BITBUCKET_TOKEN` on the first `:` and URL-encode each part before calling `git remote set-url`. This avoids breaking usernames or emails that contain reserved URL characters such as `@`:
+
+```bash
+BB_USER="${BITBUCKET_TOKEN%%:*}" && \
+BB_PASS="${BITBUCKET_TOKEN#*:}" && \
+ENCODED_USER=$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$BB_USER") && \
+ENCODED_PASS=$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$BB_PASS") && \
+git remote set-url origin "https://${ENCODED_USER}:${ENCODED_PASS}@bitbucket.org/username/repo.git"
+```
+
+Atlassian's Bitbucket Cloud docs recommend avoiding long-lived credentials in the remote URL when possible. Their API token examples use either `https://{bitbucket_username}:{api_token}@...` or `https://x-bitbucket-api-token-auth:{api_token}@...`; OpenHands users should only construct those URLs on demand, with proper URL encoding.
+
+Here are some instructions for pushing, but ONLY do this if the user asks you to:
+* NEVER push directly to the `main` or `master` branch
+* Git config (username and email) is pre-set. Do not modify.
+* You may already be on a branch starting with `openhands-workspace`. Create a new branch with a better name before pushing.
+* Use the `create_bitbucket_pr` tool to create a pull request, if you haven't already
+* Once you've created your own branch or a pull 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.
+* Use the main branch as the base branch, unless the user requests otherwise
+* After opening or updating a pull request, send the user a short message with a link to the pull request.
+* Do NOT mark a pull request as ready to review unless the user explicitly says so
+* 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:
+```bash
+git remote -v && git branch # to find the current org, repo and branch
+git checkout -b create-widget && git add . && git commit -m "Create widget" && git push -u origin create-widget
+```

package/skills/bitbucket-data-center/.plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "bitbucket-data-center",
+  "version": "1.0.0",
+  "description": "Bitbucket Data Center (self-hosted Bitbucket Server) specifics — authenticate with BITBUCKET_DATA_CENTER_TOKEN, use the REST API 1.0, PROJECT/repo_slug repositories, scm/ git remotes, and the create_bitbucket_data_center_pr tool. Loaded on demand by the bitbucket skill once a Data Center environment is detected.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "bitbucket",
+    "bitbucket-data-center",
+    "bitbucket-server",
+    "git",
+    "pull-request"
+  ]
+}

package/skills/bitbucket-data-center/README.md

@@ -0,0 +1,20 @@
+# Bitbucket Data Center
+
+Bitbucket Data Center (self-hosted Bitbucket Server) specifics — `BITBUCKET_DATA_CENTER_TOKEN`
+auth, REST API 1.0, `PROJECT/repo_slug` repositories, `scm/` git remotes, and the
+`create_bitbucket_data_center_pr` tool.
+
+## Triggers
+
+This skill has no auto-injection triggers. It is **invoke-only**: it is loaded on demand
+via the `invoke_skill` tool, normally by the [`bitbucket`](../bitbucket/) hub skill after
+it detects a Bitbucket Data Center environment (i.e. `BITBUCKET_DATA_CENTER_TOKEN` is set).
+
+## Details
+
+See [`SKILL.md`](SKILL.md) for the full content, including authenticated `scm/` git remote
+construction and pull request instructions. Note the key differences from Bitbucket Cloud:
+the REST API is version `1.0` under `https://{domain}/rest/api/1.0`, repositories are
+addressed as `PROJECT/repo_slug` (project key), git remotes use the
+`scm/{project}/{repo}.git` path, and pull requests are opened with
+`create_bitbucket_data_center_pr`.

package/skills/bitbucket-data-center/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: bitbucket-data-center
+description: Bitbucket Data Center (self-hosted Bitbucket Server) specifics — authenticate with BITBUCKET_DATA_CENTER_TOKEN, use the REST API 1.0, PROJECT/repo_slug repositories, scm/ git remotes, and the create_bitbucket_data_center_pr tool. Loaded on demand by the bitbucket skill once a Data Center environment is detected.
+---
+
+You are working with **Bitbucket Data Center** (self-hosted Bitbucket Server). You have
+access to an environment variable, `BITBUCKET_DATA_CENTER_TOKEN`, which contains a basic
+auth token in the format `username:your-token` that allows you to interact with the git
+repository and the REST API.
+
+> Environment variable names are case-sensitive. If `BITBUCKET_DATA_CENTER_TOKEN` is not
+> present, use whichever case variant actually exists (for example
+> `bitbucket_data_center_token`). Run `env | grep -i 'bitbucket_data_center'` to find it.
+
+- REST API base URL: `https://{domain}/rest/api/1.0`
+- Repository identifier format: `PROJECT/repo_slug` (project key, slash, repo slug)
+
+You can use this token to interact with the Bitbucket Data Center REST API:
+```bash
+curl -u "${BITBUCKET_DATA_CENTER_TOKEN}" https://{domain}/rest/api/1.0/...
+```
+
+<IMPORTANT>
+ALWAYS use the Bitbucket Data Center API for operations instead of a web browser.
+ALWAYS use the `create_bitbucket_data_center_pr` tool to open a pull request
+</IMPORTANT>
+
+If you encounter authentication issues when pushing to Bitbucket Data Center (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://${BITBUCKET_DATA_CENTER_TOKEN}@{domain}/scm/{project_lower}/{repo}.git`
+
+The token is a `username:token` pair, so if the username or token contains characters that are reserved in URLs (such as `@`), split on the first `:` and URL-encode each part before embedding it in a remote:
+
+```bash
+BB_USER="${BITBUCKET_DATA_CENTER_TOKEN%%:*}" && \
+BB_PASS="${BITBUCKET_DATA_CENTER_TOKEN#*:}" && \
+ENCODED_USER=$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$BB_USER") && \
+ENCODED_PASS=$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$BB_PASS") && \
+git remote set-url origin "https://${ENCODED_USER}:${ENCODED_PASS}@{domain}/scm/{project_lower}/{repo}.git"
+```
+
+Here are some instructions for pushing, but ONLY do this if the user asks you to:
+* NEVER push directly to the `main` or `master` branch
+* Git config (username and email) is pre-set. Do not modify.
+* You may already be on a branch starting with `openhands-workspace`. Create a new branch with a better name before pushing.
+* Use the `create_bitbucket_data_center_pr` tool to create a pull request, if you haven't already
+* Once you've created your own branch or a pull 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.
+* Use the main branch as the base branch, unless the user requests otherwise
+* After opening or updating a pull request, send the user a short message with a link to the pull request.
+* Do NOT mark a pull request as ready to review unless the user explicitly says so
+* 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:
+```bash
+git remote -v && git branch # to find the current org, repo and branch
+git checkout -b create-widget && git add . && git commit -m "Create widget" && git push -u origin create-widget
+```

package/skills/code-review/SKILL.md

@@ -115,7 +115,7 @@ Require:
 8. **Dependency Changes**
 If dependency lock changes have downgraded a dependency, comment pointing that out to make sure it was intentional.
 
-When a PR adds a new dependency or bumps an existing one, review the upstream release for supply chain risk. If any target version was published less than 7 days ago, do **NOT** approve the PR yet — leave a blocking review comment and wait until the version is at least 7 days old. Read `references/supply-chain-security.md` for the full verification checklist including risk-based scrutiny tiers, concrete commands for checking release provenance, and escalation guidance.
+When a PR adds a new dependency or bumps an existing one, review the upstream release for supply chain risk. If any target version was published less than 7 days ago, do **NOT** approve the PR yet — leave a blocking review comment and wait until the version is at least 7 days old. First-party packages maintained by the same organization as the reviewed repository are intentionally excluded from the 7-day waiting rule, but still scrutinize them for supply-chain risk using the checklist. Read `references/supply-chain-security.md` for the full verification checklist including risk-based scrutiny tiers, concrete commands for checking release provenance, and escalation guidance.
 
 9. **Risk and Safety Evaluation**
 Read `references/risk-evaluation.md` for the full risk evaluation framework including risk levels (🟢 Low / 🟡 Medium / 🔴 High), risk factors, escalation guidance, and repo-specific risk rules.

package/skills/code-review/references/supply-chain-security.md

@@ -7,7 +7,7 @@ When a PR adds a new dependency or bumps an existing one, review the upstream re
 Release recency is the primary risk signal - even widely-used, established packages can be compromised (e.g., LiteLLM was a popular package with high download counts when it was hijacked). Check when the target version was published before choosing a tier.
 
 **Apply full scrutiny** (all checks below) when:
-- The target version was published less than 7 days ago - regardless of package popularity or age. For PyPI: visit `https://pypi.org/project/<package>/<version>/` and check the "Released" date. For npm: run `npm view <package>@<version> time`. Recent releases have not had time for community vetting, and this is exactly the window supply chain attackers exploit. Do **NOT** approve the PR while the target version is still younger than 7 days; wait until it ages out, then complete the rest of the checklist.
+- The target version was published less than 7 days ago - regardless of package popularity or age, except first-party packages maintained by the same organization as the reviewed repository. First-party packages are intentionally excluded from the 7-day waiting rule: do not block solely on freshness, but still scrutinize them for supply-chain risk using this checklist. For PyPI: visit `https://pypi.org/project/<package>/<version>/` and check the "Released" date. For npm: run `npm view <package>@<version> time`. Recent releases have not had time for community vetting, and this is exactly the window supply chain attackers exploit.
 - Adding a dependency not previously used in this project
 - Upgrading a package that was first published less than 6 months ago (check oldest version at `https://pypi.org/project/<package>/#history` or `npm view <package> time | head -3`) or has low weekly downloads (for PyPI: check `https://pypistats.org/packages/<package>` for weekly downloads; for npm: see weekly downloads on the package page at `https://www.npmjs.com/package/<package>`; use <10k on PyPI / <1k on npm as thresholds)
 - The dependency includes native code, install hooks, or system-level access
@@ -28,4 +28,4 @@ Release recency is the primary risk signal - even widely-used, established packa
 
 ## Escalation Guidance
 
-Escalate to 🔴 High Risk if any high-severity signal is present: yanked/retracted versions, source-to-package divergence, or new install-time behavior (post-install scripts, `.pth` files). For medium-severity signals (brand-new release with no adoption signal, missing release notes), escalate only when combined with other signals from this checklist (medium or high severity) or when the package is under full scrutiny. If a dependency is under full scrutiny solely because the target version is newer than 7 days, do **NOT** approve until it is at least 7 days old; after that, re-evaluate it using the rest of this checklist. For dependencies under standard scrutiny, brand-new publication alone is not sufficient to escalate - established packages with frequent release cycles routinely publish new versions.
+Escalate to 🔴 High Risk if any high-severity signal is present: yanked/retracted versions, source-to-package divergence, or new install-time behavior (post-install scripts, `.pth` files). For medium-severity signals (brand-new release with no adoption signal, missing release notes), escalate only when combined with other signals from this checklist (medium or high severity) or when the package is under full scrutiny. If a dependency is under full scrutiny solely because the target version is newer than 7 days, do **NOT** approve until it is at least 7 days old unless it is first-party; after that, re-evaluate it using the rest of this checklist. For first-party packages, do not block solely on freshness, but still document the supply-chain risk review. For dependencies under standard scrutiny, brand-new publication alone is not sufficient to escalate - established packages with frequent release cycles routinely publish new versions.

package/skills/github-pr-reviewer/references/state-schema.md

@@ -1,12 +1,19 @@
-# State File Schema
+# State Schema
 
-The automation maintains a JSON state file that persists across polling runs.
+The automation maintains a JSON state document that persists across polling runs.
 It is the source of truth for which trigger-label events have queued reviews
 and which conversations are still active.
 
 ---
 
-## File Location
+## Storage
+
+**Primary (cloud):** The state is stored in the automation service's built-in KV
+store under the key `"state"`. The KV store is available when `AUTOMATION_KV_TOKEN`
+is injected into the run environment. Each automation has its own isolated namespace.
+
+**Fallback (local/dev):** When the KV store is not available, the state is written
+to a local JSON file at:
 
 ```
 {WORKSPACE_BASE_ROOT}/automation-state/github_pr_reviewer_label_event_{automation_id}.json
@@ -116,8 +123,15 @@ Trigger label applied on GitHub
 ## Resetting State
 
 To force the automation to reconsider previous label events, delete the state
-file:
+from the KV store (cloud) or the fallback file (local).
+
+**Cloud (KV store):**
+```bash
+curl -X DELETE "${OPENHANDS_HOST}/api/automation/v1/kv/state" \
+  -H "Authorization: Bearer ${AUTOMATION_KV_TOKEN}"
+```
 
+**Local (file fallback):**
 ```bash
 rm ~/.openhands/workspaces/automation-state/github_pr_reviewer_label_event_<id>.json
 ```