@openhands/extensions 0.5.0 → 0.6.0

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

package/skills/github-repo-monitor/scripts/main.py

@@ -108,14 +108,47 @@ def fire_callback(
         print(f"Callback error (non-fatal): {exc}")
 
 
-# ── State management ───────────────────────────────────────────────────────────
+# ── State persistence (KV store with local-file fallback) ─────────────────────
 
-def _state_file_path() -> str:
-    """Derive a persistent storage path from WORKSPACE_BASE.
+_KV_TOKEN = os.environ.get("AUTOMATION_KV_TOKEN", "")
+_KV_BASE = os.environ.get("AUTOMATION_API_URL", "").rstrip("/")
+_STATE_KEY = "state"
 
-    WORKSPACE_BASE = {root}/automation-runs/{run_id}
-    State lives two levels up at {root}/automation-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:
+    """Derive a persistent storage path from WORKSPACE_BASE (file fallback only)."""
     workspace_base = os.environ.get("WORKSPACE_BASE", "")
     event_payload = json.loads(os.environ.get("AUTOMATION_EVENT_PAYLOAD", "{}"))
     automation_id = event_payload.get("automation_id", "default")
@@ -137,25 +170,42 @@ def _default_since() -> str:
     ).strftime("%Y-%m-%dT%H:%M:%SZ")
 
 
-def load_state(path: str) -> dict:
+def _default_state() -> dict:
+    return {
+        "version": 1,
+        "repo": REPO,
+        "last_poll": _default_since(),
+        "conversations": {},
+        "processed_comment_ids": [],
+    }
+
+
+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 {
-        "version": 1,
-        "repo": REPO,
-        "last_poll": _default_since(),
-        "conversations": {},       # issue_number (str) → ConversationRecord
-        "processed_comment_ids": [],  # list of int comment IDs already handled
-    }
+    return _default_state()
 
 
-def save_state(path: str, state: dict) -> None:
+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()
     with open(path, "w") as f:
         json.dump(state, f, indent=2)
+    print(f"State saved to {path}")
 
 
 # ── GitHub API helpers ─────────────────────────────────────────────────────────
@@ -797,8 +847,7 @@ def _check_conversation_completion(
 
 def main() -> str | None:
     """Run one polling cycle. Returns the last conversation ID created, if any."""
-    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()
@@ -899,8 +948,7 @@ def main() -> str | None:
     state["processed_comment_ids"] = trimmed
     state["conversations"] = conversations
 
-    save_state(state_path, state)
-    print(f"State saved → {state_path}")
+    save_state(state)
     return last_conversation_id
 
 

package/skills/github-repo-monitor/tests/test_main.py

@@ -29,10 +29,20 @@ def _make_comment(body="hello @openhands", login="octocat", user_type="User"):
 
 # ── State file tests ───────────────────────────────────────────────────────────
 
+def _no_kv(path):
+    """Return a pair of patches: KV disabled, file path pinned to *path*."""
+    return (
+        patch("main._kv_available", return_value=False),
+        patch("main._state_file_path", return_value=path),
+    )
+
+
 class TestLoadState(unittest.TestCase):
 
     def test_missing_file_returns_default(self):
-        state = main.load_state("/nonexistent/path/state.json")
+        with patch("main._kv_available", return_value=False), \
+             patch("main._state_file_path", return_value="/nonexistent/path/state.json"):
+            state = main.load_state()
         self.assertIn("conversations", state)
         self.assertIn("processed_comment_ids", state)
         self.assertEqual(state["version"], 1)
@@ -42,7 +52,9 @@ class TestLoadState(unittest.TestCase):
             json.dump({"version": 1, "custom": "value", "conversations": {}}, f)
             path = f.name
         try:
-            state = main.load_state(path)
+            with patch("main._kv_available", return_value=False), \
+                 patch("main._state_file_path", return_value=path):
+                state = main.load_state()
             self.assertEqual(state["custom"], "value")
         finally:
             os.unlink(path)
@@ -52,7 +64,9 @@ class TestLoadState(unittest.TestCase):
             f.write("{this is not valid json!!!}")
             path = f.name
         try:
-            state = main.load_state(path)
+            with patch("main._kv_available", return_value=False), \
+                 patch("main._state_file_path", return_value=path):
+                state = main.load_state()
             # Should return the default state rather than raising.
             self.assertIn("conversations", state)
             self.assertEqual(state["version"], 1)
@@ -64,7 +78,9 @@ class TestLoadState(unittest.TestCase):
             f.write("")
             path = f.name
         try:
-            state = main.load_state(path)
+            with patch("main._kv_available", return_value=False), \
+                 patch("main._state_file_path", return_value=path):
+                state = main.load_state()
             self.assertIn("conversations", state)
         finally:
             os.unlink(path)
@@ -81,14 +97,55 @@ class TestSaveAndLoadRoundtrip(unittest.TestCase):
         with tempfile.NamedTemporaryFile(suffix=".json", delete=False) as f:
             path = f.name
         try:
-            main.save_state(path, data)
-            loaded = main.load_state(path)
+            with patch("main._kv_available", return_value=False), \
+                 patch("main._state_file_path", return_value=path):
+                main.save_state(data)
+                loaded = main.load_state()
             self.assertEqual(loaded["conversations"]["42"]["conversation_id"], "abc")
             self.assertEqual(loaded["processed_comment_ids"], [1, 2, 3])
         finally:
             os.unlink(path)
 
 
+class TestKVState(unittest.TestCase):
+
+    def test_load_reads_value_from_kv(self):
+        kv_data = {"version": 1, "conversations": {"7": {"conversation_id": "kv-c"}},
+                   "processed_comment_ids": []}
+        with patch("main._kv_available", return_value=True), \
+             patch("main._kv_get", return_value=kv_data) as mock_get:
+            state = main.load_state()
+        self.assertEqual(state["conversations"]["7"]["conversation_id"], "kv-c")
+        mock_get.assert_called_once_with("state")
+
+    def test_load_returns_default_on_kv_miss(self):
+        with patch("main._kv_available", return_value=True), \
+             patch("main._kv_get", return_value=None):
+            state = main.load_state()
+        self.assertIn("conversations", state)
+        self.assertEqual(state["version"], 1)
+
+    def test_save_writes_to_kv(self):
+        data = {"version": 1, "conversations": {}, "processed_comment_ids": []}
+        with patch("main._kv_available", return_value=True), \
+             patch("main._kv_set") as mock_set:
+            main.save_state(data)
+        mock_set.assert_called_once_with("state", data)
+
+    def test_kv_error_propagates_on_load(self):
+        with patch("main._kv_available", return_value=True), \
+             patch("main._kv_get", side_effect=RuntimeError("network error")):
+            with self.assertRaises(RuntimeError):
+                main.load_state()
+
+    def test_kv_error_propagates_on_save(self):
+        data = {"version": 1, "conversations": {}, "processed_comment_ids": []}
+        with patch("main._kv_available", return_value=True), \
+             patch("main._kv_set", side_effect=RuntimeError("network error")):
+            with self.assertRaises(RuntimeError):
+                main.save_state(data)
+
+
 # ── Bot detection tests ────────────────────────────────────────────────────────
 
 class TestIsBotComment(unittest.TestCase):
@@ -214,8 +271,10 @@ class TestProcessedIdDeduplication(unittest.TestCase):
         try:
             state = {"version": 1, "conversations": {},
                      "processed_comment_ids": [101, 202, 303]}
-            main.save_state(path, state)
-            loaded = main.load_state(path)
+            with patch("main._kv_available", return_value=False), \
+                 patch("main._state_file_path", return_value=path):
+                main.save_state(state)
+                loaded = main.load_state()
             self.assertIn(101, loaded["processed_comment_ids"])
             self.assertIn(303, loaded["processed_comment_ids"])
             self.assertNotIn(404, loaded["processed_comment_ids"])