@openhands/extensions 0.4.2 → 0.6.0

package/pyproject.toml

@@ -1,12 +1,26 @@
 [project]
-name = "extensions"
-version = "0.4.2"
-description = "OpenHands extensions, plugins, and skills"
+name = "openhands-extensions"
+version = "0.6.0"
+description = "OpenHands extensions, plugins, and skills (Python bindings for the integration catalog)"
 requires-python = ">=3.12"
 
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["python/openhands_extensions"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"integrations/catalog" = "openhands_extensions/catalog"
+
 [dependency-groups]
 test = [
     "pytest>=8.0",
     "requests>=2.31",
     "openhands-sdk>=0.3",
 ]
+
+[tool.pytest.ini_options]
+pythonpath = ["python"]
+testpaths = ["tests"]

package/python/openhands_extensions/__init__.py

@@ -0,0 +1,24 @@
+"""Python bindings for the OpenHands extensions catalogs.
+
+Mirrors the JavaScript package (``@openhands/extensions``): both read the same
+hand-authored ``integrations/catalog/<id>.json`` files. The JavaScript package
+uses a generated static import index; the Python package loads the packaged
+individual JSON files directly. See ``integrations.py`` for the catalog API,
+including filtering by connector type (mcp / oauth).
+"""
+
+from __future__ import annotations
+
+from ._version import __version__
+from .integrations import (
+    INTEGRATION_CATALOG_SNAPSHOT,
+    get_integration_catalog_entry,
+    list_integration_catalog,
+)
+
+__all__ = [
+    "INTEGRATION_CATALOG_SNAPSHOT",
+    "__version__",
+    "get_integration_catalog_entry",
+    "list_integration_catalog",
+]

package/python/openhands_extensions/_version.py

@@ -0,0 +1,24 @@
+"""Package version, derived from installed package metadata.
+
+The single source of truth is ``pyproject.toml``'s ``[project].version``
+(which ``release-please`` bumps together with ``package.json`` via
+``release-please-config.json`` -> ``extra-files``). At runtime we read the
+installed distribution metadata via ``importlib.metadata`` so there is no
+second hand-maintained version string. ``_FALLBACK_VERSION`` is only used
+when the package is imported without being installed (e.g. straight off a
+source checkout with no build), and ``tests/test_version_alignment.py``
+asserts it stays in lock-step with ``pyproject.toml`` / ``package.json``.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+#: Fallback used only when the package is not installed (no dist metadata).
+#: Kept in lock-step with pyproject.toml/package.json by the version test.
+_FALLBACK_VERSION = "0.6.0"
+
+try:
+    __version__: str = version("openhands-extensions")
+except PackageNotFoundError:  # not installed (e.g. raw source checkout)
+    __version__ = _FALLBACK_VERSION

package/python/openhands_extensions/integrations.py

@@ -0,0 +1,92 @@
+"""Python bindings for the OpenHands extensions integration catalog.
+
+The source of truth is the hand-authored ``integrations/catalog/<id>.json``
+directory. Wheels include those individual JSON files directly; no aggregate
+catalog JSON is authored or packaged.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+from functools import lru_cache
+from importlib import resources
+from pathlib import Path
+from typing import Any, Iterable
+
+__all__ = [
+    "INTEGRATION_CATALOG_SNAPSHOT",
+    "get_integration_catalog_entry",
+    "list_integration_catalog",
+]
+
+
+def _repo_catalog_dir() -> Path:
+    return Path(__file__).resolve().parents[2] / "integrations" / "catalog"
+
+
+def _catalog_files() -> Iterable[Any]:
+    packaged = resources.files(__package__).joinpath("catalog")
+    if packaged.is_dir():
+        return sorted(
+            (path for path in packaged.iterdir() if path.name.endswith(".json")),
+            key=lambda path: path.name,
+        )
+
+    repo_catalog = _repo_catalog_dir()
+    return sorted(repo_catalog.glob("*.json"), key=lambda path: path.name)
+
+
+def _read_json(path: Any) -> dict[str, Any]:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+@lru_cache(maxsize=1)
+def _integrations() -> tuple[dict[str, Any], ...]:
+    entries = [_read_json(path) for path in _catalog_files()]
+    entries.sort(
+        key=lambda entry: (-(entry.get("popularityRank") if entry.get("popularityRank") is not None else -1), entry["id"]),
+    )
+    return tuple(entries)
+
+
+@lru_cache(maxsize=1)
+def _integration_by_id() -> dict[str, dict[str, Any]]:
+    return {entry["id"]: entry for entry in _integrations()}
+
+
+def _entry_supports_mcp(entry: dict[str, Any]) -> bool:
+    return any(option.get("provider") == "mcp" for option in entry.get("connectionOptions", []))
+
+
+def _entry_supports_oauth(entry: dict[str, Any]) -> bool:
+    return any(
+        option.get("auth", {}).get("strategy") == "oauth2"
+        for option in entry.get("connectionOptions", [])
+    )
+
+
+def list_integration_catalog(
+    mcp: bool | None = None,
+    oauth: bool | None = None,
+) -> list[dict[str, Any]]:
+    """Return the integration catalog, optionally filtered by connector type."""
+    result = []
+    for entry in _integrations():
+        if mcp is not None and _entry_supports_mcp(entry) != mcp:
+            continue
+        if oauth is not None and _entry_supports_oauth(entry) != oauth:
+            continue
+        result.append(copy.deepcopy(entry))
+    return result
+
+
+def get_integration_catalog_entry(id: str) -> dict[str, Any] | None:
+    """Return one integration catalog entry by id, or ``None``."""
+    entry = _integration_by_id().get(id)
+    return copy.deepcopy(entry) if entry is not None else None
+
+
+INTEGRATION_CATALOG_SNAPSHOT: dict[str, Any] = {
+    "integrations": copy.deepcopy(list(_integrations()))
+}

package/release-please-config.json

@@ -9,7 +9,8 @@
       "include-component-in-tag": false,
       "skip-changelog": true,
       "extra-files": [
-        { "type": "toml", "path": "pyproject.toml", "jsonpath": "$.project.version" }
+        { "type": "toml", "path": "pyproject.toml", "jsonpath": "$.project.version" },
+        "python/openhands_extensions/_version.py"
       ]
     }
   }

package/scripts/build-integration-catalog.mjs

@@ -0,0 +1,45 @@
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const root = process.cwd();
+const catalogDir = path.join(root, "integrations", "catalog");
+const outputPath = path.join(root, "integrations", "catalog-index.js");
+
+const files = (await readdir(catalogDir))
+  .filter((file) => file.endsWith(".json"))
+  .sort((left, right) => left.localeCompare(right));
+
+const integrations = await Promise.all(
+  files.map(async (file) => ({
+    file,
+    entry: JSON.parse(await readFile(path.join(catalogDir, file), "utf8")),
+  })),
+);
+
+integrations.sort((left, right) => {
+  const rank = (right.entry.popularityRank ?? -1) - (left.entry.popularityRank ?? -1);
+  return rank || left.entry.id.localeCompare(right.entry.id);
+});
+
+const indexedIntegrations = integrations.map((integration, index) => ({
+  ...integration,
+  importName: `entry${index}`,
+}));
+
+const imports = indexedIntegrations
+  .map(({ file, importName }) => `import ${importName} from "./catalog/${file}" with { type: "json" };`)
+  .join("\n");
+const entries = indexedIntegrations.map(({ importName }) => `  ${importName},`).join("\n");
+
+const header = `// This file is auto-generated by scripts/build-integration-catalog.mjs.
+// Do not edit it manually. To update it after changing integrations/catalog/*.json,
+// run: npm run build:integrations
+
+`;
+const body = `${header}${imports}
+
+export const INTEGRATION_CATALOG_ENTRIES = [
+${entries}
+];
+`;
+await writeFile(outputPath, body);

package/skills/agent-canvas-environment/.plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "agent-canvas-environment",
+  "version": "1.0.0",
+  "description": "Work effectively inside a local Agent Canvas environment, including local agent-server auth, frontend/backend port discovery, safe workspace hygiene, and local conversation delegation.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "agent-canvas",
+    "openhands",
+    "local",
+    "conversation",
+    "delegation"
+  ]
+}

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,141 @@
+---
+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:
+
+- current `/api/settings` as the base agent profile
+- a fresh absolute workspace directory
+- `initial_message.run: true`
+- `worktree: false` when the workspace is already isolated
+
+Template:
+
+```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"
+
+SETTINGS_JSON="$(curl -sS -H "X-Session-API-Key: $KEY" "$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" '
+  def agent_settings:
+    ($settings.agent_settings // {})
+    | del(.schema_version)
+    | . + {
+        agent_context: ((.agent_context // {}) + {
+          load_public_skills: true,
+          load_user_skills: true,
+          load_project_skills: true
+        })
+      };
+  ($settings.conversation_settings // {}) as $conv |
+  {
+    agent_settings: agent_settings,
+    workspace: {kind: "LocalWorkspace", working_dir: $workdir},
+    confirmation_policy: {kind: "NeverConfirm"},
+    max_iterations: (($conv.max_iterations // 80) | if . == null then 80 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}'
+```
+
+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/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
 ```

package/skills/github-pr-reviewer/scripts/main.py

@@ -67,6 +67,45 @@ def fire_callback(
         print(f"Callback error (non-fatal): {exc}")
 
 
+# ── State persistence (KV store with local-file fallback) ─────────────────────
+
+_KV_TOKEN = os.environ.get("AUTOMATION_KV_TOKEN", "")
+_KV_BASE = os.environ.get("AUTOMATION_API_URL", "").rstrip("/")
+_STATE_KEY = "state"
+
+
+def _kv_available() -> bool:
+    return bool(_KV_TOKEN and _KV_BASE)
+
+
+def _kv_get(key: str) -> dict | None:
+    req = urllib.request.Request(
+        f"{_KV_BASE}/v1/kv/{key}",
+        headers={"Authorization": f"Bearer {_KV_TOKEN}"},
+    )
+    try:
+        with urllib.request.urlopen(req) as r:
+            return json.loads(r.read())["value"]
+    except urllib.error.HTTPError as exc:
+        if exc.code == 404:
+            return None
+        raise
+
+
+def _kv_set(key: str, value: dict) -> None:
+    req = urllib.request.Request(
+        f"{_KV_BASE}/v1/kv/{key}",
+        data=json.dumps(value).encode(),
+        headers={
+            "Authorization": f"Bearer {_KV_TOKEN}",
+            "Content-Type": "application/json",
+        },
+        method="PUT",
+    )
+    with urllib.request.urlopen(req) as r:
+        r.read()
+
+
 def _state_file_path() -> str:
     workspace_base = os.environ.get("WORKSPACE_BASE", "")
     event_payload = json.loads(os.environ.get("AUTOMATION_EVENT_PAYLOAD", "{}"))
@@ -82,13 +121,7 @@ def _state_file_path() -> str:
     return str(state_dir / f"github_pr_reviewer_label_event_{automation_id}.json")
 
 
-def load_state(path: str) -> dict:
-    if os.path.exists(path):
-        try:
-            with open(path) as f:
-                return json.load(f)
-        except (json.JSONDecodeError, OSError) as exc:
-            print(f"Warning: state file {path} unreadable ({exc}); starting fresh")
+def _default_state() -> dict:
     return {
         "version": 2,
         "repo": REPO,
@@ -98,11 +131,34 @@ def load_state(path: str) -> dict:
     }
 
 
-def save_state(path: str, state: dict) -> None:
+def load_state() -> dict:
+    if _kv_available():
+        data = _kv_get(_STATE_KEY)
+        if data is not None:
+            print("State loaded from KV store")
+            return data
+        return _default_state()
+    path = _state_file_path()
+    if os.path.exists(path):
+        try:
+            with open(path) as f:
+                return json.load(f)
+        except (json.JSONDecodeError, OSError) as exc:
+            print(f"Warning: state file {path} unreadable ({exc}); starting fresh")
+    return _default_state()
+
+
+def save_state(state: dict) -> None:
+    if _kv_available():
+        _kv_set(_STATE_KEY, state)
+        print("State saved to KV store")
+        return
+    path = _state_file_path()
     tmp_path = f"{path}.tmp"
     with open(tmp_path, "w") as f:
         json.dump(state, f, indent=2, sort_keys=True)
     os.replace(tmp_path, path)
+    print(f"State saved to {path}")
 
 
 def _github_request(
@@ -522,8 +578,7 @@ def _check_conversation_completion(
 
 
 def main() -> str | None:
-    state_path = _state_file_path()
-    state = load_state(state_path)
+    state = load_state()
     agent_url = os.environ.get("AGENT_SERVER_URL", "").rstrip("/")
     api_key = _get_env_key()
 
@@ -591,8 +646,7 @@ def main() -> str | None:
     state["repo"] = REPO
     state["trigger_label"] = TRIGGER_LABEL
     state["updated_at"] = time.time()
-    save_state(state_path, state)
-    print(f"State saved → {state_path}")
+    save_state(state)
     return last_conversation_id
 
 

package/skills/github-repo-monitor/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.
-This file is the source of truth for which conversations are active, which
+The automation maintains a JSON state document that persists across polling runs.
+This document is the source of truth for which conversations are active, which
 comment IDs have already been processed, and the timestamp of the last poll.
 
 ---
 
-## 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_poller_{automation_id}.json