@openhands/extensions 0.4.2 → 0.6.0

package/skills/openhands-api/README.md

@@ -1,9 +1,11 @@
 # openhands-api
 
-Reference skill + minimal clients for the **OpenHands Cloud API** (V1).
+Reference skill + minimal clients for the **OpenHands Cloud API** (V1) and common **agent-server APIs**.
 
 This skill now also covers the **multi-conversation delegation pattern**: start additional Cloud conversations when you want fresh context windows, background work, or parallel tasks.
 
+It also covers direct local Agent Canvas backend conversations when you need to call a local agent server with `X-Session-API-Key` instead of creating a Cloud app conversation.
+
 - Skill instructions and endpoint overview: [`SKILL.md`](./SKILL.md)
 - Minimal Python client: [`scripts/openhands_api.py`](./scripts/openhands_api.py)
 - Minimal TypeScript client: [`scripts/openhands_api.ts`](./scripts/openhands_api.ts)
@@ -42,6 +44,8 @@ If `app_conversation_id` is missing from the initial response, fetch it via:
 This skill is aligned against:
 
 - `OpenHands/docs/openhands/usage/cloud/cloud-api.mdx`
+- `OpenHands/docs/openhands/usage/agent-canvas/backend-setup/local.mdx`
+- `OpenHands/docs/sdk/arch/agent-server.mdx`
 - `OpenHands/docs/openhands/usage/api/v1.mdx`
 - `OpenHands/OpenHands/openhands/app_server/v1_router.py`
 - `OpenHands/OpenHands/openhands/app_server/app_conversation/app_conversation_router.py`

package/skills/openhands-api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: openhands-api
-description: Reference skill for the OpenHands Cloud REST API (V1), including how to start additional cloud conversations for fresh-context or delegated work. Use when you need to automate common OpenHands Cloud actions; don't use for general sandbox/dev tasks unrelated to the OpenHands API.
+description: Reference skill for the OpenHands Cloud REST API (V1) and agent-server APIs, including how to start additional cloud or local backend conversations for fresh-context or delegated work.
 triggers:
 - openhands-api
 - openhands-api-v1
@@ -10,14 +10,15 @@ triggers:
 - oh-cloud-api-v1
 ---
 
-This skill documents the **OpenHands Cloud API** (V1) and provides small, easy-to-copy clients.
+This skill documents the **OpenHands Cloud API** (V1), commonly used **agent-server APIs**, and small, easy-to-copy clients.
 
-It is intentionally focused on common OpenHands Cloud workflows:
+It is intentionally focused on common OpenHands API workflows:
 
 - Defaults to OpenHands Cloud (`https://app.all-hands.dev`).
 - Targets the **V1 app server REST API** under `/api/v1/...`.
 - Includes a few **agent server** endpoints (inside a sandbox) that use `X-Session-API-Key`.
 - Covers the **multi-conversation delegation pattern**: start separate Cloud conversations when you want fresh context windows or background work.
+- Covers **local Agent Canvas backend conversations**: start or inspect conversations by calling a local agent server directly.
 
 ## When to use this skill
 
@@ -28,6 +29,7 @@ Use this skill when you need to:
 - monitor execution status for long-running jobs
 - create separate Cloud conversations for parallel or background work
 - access sandbox agent-server endpoints once a conversation is running
+- start or inspect conversations on a local Agent Canvas backend or local agent server
 
 ## Auth
 
@@ -73,6 +75,72 @@ agent_server_url = conversation_url.rsplit("/api/conversations", 1)[0]
 
 If those fields are not present on the conversation record, list/search sandboxes (`GET /api/v1/sandboxes/search`) and use the sandbox referenced by the conversation to locate the agent server URL + session key.
 
+### Local Agent Canvas backend
+
+Use the local backend flow only for local Agent Canvas / agent-server development, such as `agent-canvas`, `agent-canvas --backend-only`, or `npm run dev` with ingress at `http://localhost:8000`. This calls the agent server directly with `X-Session-API-Key`. It is not an automation, and it is different from OpenHands Cloud delegation through `POST /api/v1/app-conversations`, which uses Bearer auth against the Cloud app API and may return asynchronous start-task records.
+
+When Agent Canvas runs locally, the launcher uses `LOCAL_BACKEND_API_KEY` when it is set. Otherwise it generates and persists the session API key at `~/.openhands/agent-canvas/api-key.txt`. Set `OH_SESSION_API_KEY_PATH` to override the persisted key path. Never print, log, or paste the actual key; use command substitution or an environment variable in examples and scripts.
+
+```bash
+LOCAL_AGENT_SERVER_URL="${LOCAL_AGENT_SERVER_URL:-http://localhost:8000}"
+SESSION_API_KEY="${LOCAL_BACKEND_API_KEY:-$(cat "${OH_SESSION_API_KEY_PATH:-$HOME/.openhands/agent-canvas/api-key.txt}")}"
+```
+
+Check the local server before creating a backend conversation:
+
+```bash
+curl -sS "${LOCAL_AGENT_SERVER_URL}/server_info" \
+  -H "X-Session-API-Key: ${SESSION_API_KEY}"
+```
+
+Start a backend conversation with `POST /api/conversations`. Include the agent settings and workspace expected by that backend. Local agent-server calls use an explicit `workspace` such as `{"kind": "LocalWorkspace", "working_dir": "/workspace"}`; Cloud app-conversation delegation instead uses app-server fields such as `selected_repository` and `selected_branch`. If you are starting the conversation from an existing Agent Canvas session, pass through the current configured settings or encrypted settings rather than hard-coding secrets into scripts.
+
+```bash
+CONVERSATION_JSON=$(curl -sS -X POST "${LOCAL_AGENT_SERVER_URL}/api/conversations" \
+  -H "X-Session-API-Key: ${SESSION_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d @- <<'JSON'
+{
+  "agent": {
+    "kind": "Agent",
+    "llm": {
+      "model": "your-model-provider/your-model-name",
+      "api_key": "**********"
+    },
+    "tools": [
+      {"name": "terminal"},
+      {"name": "file_editor"},
+      {"name": "task_tracker"}
+    ]
+  },
+  "workspace": {"kind": "LocalWorkspace", "working_dir": "/workspace"},
+  "initial_message": {
+    "content": [{"text": "Summarize the current workspace."}],
+    "run": true
+  }
+}
+JSON
+)
+CONVERSATION_ID=$(python3 -c 'import json,sys; print(json.load(sys.stdin)["id"])' <<<"${CONVERSATION_JSON}")
+printf 'Conversation: %s/api/conversations/%s\n' "${LOCAL_AGENT_SERVER_URL}" "${CONVERSATION_ID}"
+```
+
+Poll status and inspect recent events:
+
+```bash
+curl -sS "${LOCAL_AGENT_SERVER_URL}/api/conversations/${CONVERSATION_ID}" \
+  -H "X-Session-API-Key: ${SESSION_API_KEY}"
+
+curl -sS "${LOCAL_AGENT_SERVER_URL}/api/conversations/${CONVERSATION_ID}/events/search?limit=20&sort_order=TIMESTAMP_DESC" \
+  -H "X-Session-API-Key: ${SESSION_API_KEY}"
+```
+
+If the same base URL serves the Agent Canvas UI, the browser route is:
+
+```bash
+printf '%s/conversations/%s\n' "${LOCAL_AGENT_SERVER_URL}" "${CONVERSATION_ID}"
+```
+
 ## Common V1 app server endpoints
 
 The following are the main endpoints implemented in the minimal client:
@@ -389,11 +457,12 @@ See also:
 
 ## Source of truth
 
-This skill is aligned against the current V1 docs and implementation:
+This skill is aligned against the current OpenHands API docs and implementation:
 
 - `OpenHands/docs/openhands/usage/cloud/cloud-api.mdx`
+- `OpenHands/docs/openhands/usage/agent-canvas/backend-setup/local.mdx`
+- `OpenHands/docs/sdk/arch/agent-server.mdx`
 - `OpenHands/docs/openhands/usage/api/v1.mdx`
 - `OpenHands/OpenHands/openhands/app_server/v1_router.py`
 - `OpenHands/OpenHands/openhands/app_server/app_conversation/app_conversation_router.py`
 - `OpenHands/OpenHands/openhands/app_server/app_conversation/app_conversation_models.py`
-

package/skills/openhands-automation/SKILL.md

@@ -106,6 +106,8 @@ def fire_callback(status="COMPLETED", error=None):
 
 Entrypoint must be `python3 main.py` (no `setup.sh` needed). Wrap your main logic in `try/except` and call `fire_callback("FAILED", str(e))` in the except block.
 
+**State persistence between runs** — polling automations that track a "last processed" timestamp or active conversation IDs must use the built-in KV store rather than local files. Local files are lost when a run ends on a cloud pod. The KV store is available when `AUTOMATION_KV_TOKEN` is injected into the run environment. See `references/custom-automation.md#state-persistence-kv-store` for ready-to-copy `kv_get` / `kv_set` / `load_state` / `save_state` helpers.
+
 ---
 
 ## Authentication
@@ -871,5 +873,5 @@ The **prompt preset** is the right default for genuinely agent-shaped work — a
 
 ## Reference Files
 
-- **`references/custom-automation.md`** — Detailed guide for custom automations: tarball uploads, code structure (SDK and no-LLM), environment variables, validation rules, and complete examples. Consult this whenever you need to evaluate or recommend the custom path (including for deterministic / cost-sensitive tasks per rule 0). Only *implement* a custom automation after the user agrees to that path.
+- **`references/custom-automation.md`** — Detailed guide for custom automations: tarball uploads, code structure (SDK and no-LLM), state persistence via the KV store, environment variables, validation rules, and complete examples. Consult this whenever you need to evaluate 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.

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

@@ -439,6 +439,170 @@ def fire_callback(status: str = "COMPLETED", error: str | None = None) -> None:
 
 ---
 
+## State Persistence (KV Store)
+
+Polling automations that run on a schedule need to remember state between runs — for example, the timestamp of the last processed event, or which conversation IDs are currently active. Storing this in a local file does not work on cloud deployments where each run may land on a fresh pod.
+
+The automation service provides a built-in key-value store scoped per-automation. It is available in every run when the service is configured with `AUTOMATION_KV_SECRET`. Detect availability by checking for `AUTOMATION_KV_TOKEN` in the environment.
+
+### KV Store API
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/v1/kv/{key}` | GET | Get value (404 if not found) |
+| `/v1/kv/{key}` | PUT | Set value (201 on create, 200 on update) |
+| `/v1/kv/{key}` | DELETE | Delete key |
+| `/v1/kv/{key}/incr` | POST | Atomic integer increment |
+| `/v1/kv/{key}/decr` | POST | Atomic integer decrement |
+| `/v1/kv/{key}/rpush` | POST | Append item to a list |
+| `/v1/kv/{key}/lpop` | POST | Pop item from front of a list |
+
+**Authentication:** `Authorization: Bearer $AUTOMATION_KV_TOKEN`
+
+**Base URL:** `$AUTOMATION_API_URL` (e.g., `https://app.all-hands.dev/api/automation`)
+
+Values are arbitrary JSON (dict, list, number, string). All keys are isolated per-automation — different automations cannot access each other's data.
+
+### KV Store Helpers
+
+Copy these helpers into any deterministic script that needs state persistence:
+
+```python
+import json, os, urllib.error, urllib.request
+
+_KV_TOKEN = os.environ.get("AUTOMATION_KV_TOKEN", "")
+_KV_BASE = os.environ.get("AUTOMATION_API_URL", "").rstrip("/")
+
+
+def kv_available() -> bool:
+    """Return True when the KV store is reachable in this run."""
+    return bool(_KV_TOKEN and _KV_BASE)
+
+
+def kv_get(key: str):
+    """Fetch a value from the KV store. Returns None if the key does not exist."""
+    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) -> None:
+    """Write a value to the KV store."""
+    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()
+```
+
+### Load / Save Pattern
+
+For polling scripts that maintain a single state document, use a KV-first pattern with a local-file fallback so the script also works in local/dev environments where the KV store is not configured:
+
+```python
+import json, os, urllib.error, urllib.request
+from pathlib import Path
+
+_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):
+    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) -> 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() -> Path:
+    workspace = os.environ.get("WORKSPACE_BASE", "")
+    if workspace:
+        root = Path(workspace).resolve().parent.parent
+    else:
+        root = Path.home() / ".openhands" / "workspaces"
+    state_dir = root / "automation-state"
+    state_dir.mkdir(parents=True, exist_ok=True)
+    payload = json.loads(os.environ.get("AUTOMATION_EVENT_PAYLOAD", "{}"))
+    automation_id = payload.get("automation_id", "default")
+    return state_dir / f"my_poller_{automation_id}.json"
+
+
+def _default_state() -> dict:
+    return {"version": 1, "last_poll": 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 path.exists():
+        try:
+            return json.loads(path.read_text())
+        except Exception as exc:
+            print(f"Warning: state file 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.with_suffix(".tmp")
+    tmp.write_text(json.dumps(state, indent=2))
+    tmp.replace(path)
+    print(f"State saved to {path}")
+```
+
+> **Why a single document?** The KV store uses a single-document model under the hood (all keys for an automation share one encrypted row). Storing your entire state under a single key like `"state"` is the most efficient pattern — it avoids multiple round-trips and ensures atomic reads and writes.
+
+---
+
 ## Environment Variables
 
 The automation service injects these environment variables into every run:
@@ -451,6 +615,8 @@ The automation service injects these environment variables into every run:
 | `AUTOMATION_CALLBACK_API_KEY` | — | Bearer token for the completion callback POST |
 | `AUTOMATION_RUN_ID` | — | Run ID to include in the completion callback payload |
 | `AUTOMATION_EVENT_PAYLOAD` | — | JSON with trigger context: `automation_id`, `automation_name`, `trigger` type, and (for webhook runs) the raw event payload |
+| `AUTOMATION_API_URL` | — | Base URL of the automation service (e.g., `https://app.all-hands.dev/api/automation`). Used to reach the KV store API |
+| `AUTOMATION_KV_TOKEN` | — | Bearer token for the KV store API. Present whenever the service has `AUTOMATION_KV_SECRET` configured. Check for this variable to detect KV availability |
 
 > **Note:** The session API key has two names: `SESSION_API_KEY` (cloud) and `OH_SESSION_API_KEYS_0` (local/dev). Always read both — see the code examples above.
 

package/skills/openhands-sdk/SKILL.md

@@ -86,18 +86,21 @@ print("All done!")
 - [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.
@@ -109,11 +112,12 @@ print("All done!")
 - [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): Run agents through a local HTTP server with RemoteConversation for client-server architecture.
+- [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.
@@ -180,7 +184,6 @@ Source: [`examples/`](https://github.com/OpenHands/software-agent-sdk/tree/main/
 - [`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)
-- [`43_mixed_marketplace_skills`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/01_standalone_sdk/43_mixed_marketplace_skills)
 - [`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)
@@ -191,6 +194,7 @@ Source: [`examples/`](https://github.com/OpenHands/software-agent-sdk/tree/main/
 - [`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)
 
 ### [`02_remote_agent_server/`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/02_remote_agent_server)
 
@@ -209,6 +213,7 @@ Source: [`examples/`](https://github.com/OpenHands/software-agent-sdk/tree/main/
 - [`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)
 
@@ -230,4 +235,5 @@ Source: [`examples/`](https://github.com/OpenHands/software-agent-sdk/tree/main/
 - [`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)
 

package/skills/slack-channel-monitor/README.md

@@ -27,8 +27,10 @@ This skill is activated by keywords:
 - **Efficient polling**: single `search.messages` call for multi-channel user
   tokens with `search:read`; falls back to one `conversations.history` call
   per channel for bot tokens
-- **Thread tracking**: new replies in a triggered thread are forwarded to the
-  running OpenHands conversation
+- **Triggered follow-ups**: Slack thread replies that repeat the trigger phrase
+  are forwarded to the existing OpenHands conversation
+- **Watch window**: completed conversations keep watching their Slack thread for
+  short follow-up periods, with quiet threads backed off automatically
 - **Reaction acknowledgement**: adds a 👀 to every message containing the
   trigger phrase
 - **Conversation link**: posts a link to the new conversation in the Slack
@@ -79,9 +81,11 @@ Each cron run (every minute):
 3. Creates an OpenHands conversation with the message and recent channel
    context as the initial prompt; posts a link to the conversation in the
    Slack thread
-4. Forwards new replies in tracked threads to the running conversation
-5. Checks active conversations - posts the agent's final response back to
-   Slack when the conversation completes
+4. Forwards triggered replies in tracked threads to the existing conversation,
+   while ignoring replies that do not contain the trigger phrase
+5. Checks active conversations - posts the agent's final response with
+   Slack's `markdown_text` field so Markdown renders correctly, then watches
+   briefly for triggered follow-up replies
 
 ## See Also
 

package/skills/slack-channel-monitor/SKILL.md

@@ -23,9 +23,12 @@ detected it:
 3. Posts a reply in the Slack thread with a link to the conversation.
 
 On every subsequent run:
-- Replies in the thread are forwarded to the running conversation.
+- New Slack thread replies are forwarded only when they contain the trigger
+  phrase, so unrelated conversation in the thread is ignored.
 - When the conversation finishes (or errors), the agent's final response is
   posted back to the Slack thread.
+- Completed conversations stay in a short follow-up watch window, allowing
+  triggered Slack replies to continue the same OpenHands conversation.
 
 > **Local mode only.** This automation targets the local OpenHands setup
 > (`dev:automation` stack). A cloud/webhook-based variant is out of scope here.
@@ -235,20 +238,27 @@ Each cron run executes `main.py`, which runs **10 polling iterations** (every
    - User token + `search:read` + > 1 channel → single `search.messages` call
      (searches for the trigger phrase across all channels).
    - Otherwise → one `conversations.history` call per channel.
-4. **Fetches thread replies**  -  one `conversations.replies` call per tracked thread.
+4. **Fetches due thread replies**  -  polls at most one tracked thread per
+   iteration using per-thread exponential backoff to stay within Slack rate
+   limits.
 5. **Processes messages** in chronological order:
    - Skips messages already in `processed_ts` (dedup across the overlap window).
    - Skips bot messages and any `ts` in `bot_message_ts`.
-   - Reply in a tracked thread (active **or** closed) → forwards to the existing
-     conversation; re-opens closed conversations automatically.
-   - Contains trigger phrase → 👀 reaction, create conversation, post link.
+   - Reply in a tracked thread whose text contains the trigger phrase → forwards
+     a follow-up request to the existing conversation and resets the follow-up
+     watch window. Replies without the trigger phrase are marked processed and
+     ignored.
+   - Contains trigger phrase outside a tracked conversation → 👀 reaction, create
+     a new conversation, post link.
      - Thread replies: agent receives full thread history for context.
      - Root messages: agent receives the trigger text only.
 6. **Checks conversation statuses**  -  for each active conversation where
    `time.time() - last_activity > 15 s`:
    - If status is `idle`, `finished`, `error`, or `stuck` → fetch the agent's
      final response via `/api/conversations/{id}/agent_final_response` and post
-     it to the Slack thread. Mark conversation `closed`.
+     it to the Slack thread using Slack's `markdown_text` field so Markdown
+     formatting renders correctly. Mark the record `watching` for five minutes
+     so triggered follow-up replies can continue the same conversation.
 7. **Advances `last_poll`** to `now - 10 s` (overlap window prevents boundary
    races). If a conversation creation failed, pins `last_poll` further back to
    retry on the next iteration.

package/skills/slack-channel-monitor/references/slack-api.md

@@ -198,10 +198,12 @@ With < 10 channels polled every minute:
 | Method | Tier | Calls/min | Headroom |
 |--------|------|-----------|---------|
 | `conversations.history` | Tier 3 | ≤ 10 | Comfortable |
-| `conversations.replies` | Tier 3 | ≤ active threads | Fine unless hundreds of threads |
+| `conversations.replies` | Tier 3 | ≤ 1 due tracked thread per iteration | Throttled with per-thread backoff |
 | `search.messages` | Tier 2 | 1 | Fine |
 | `reactions.add` | Tier 2 | ≤ triggers/min | Fine |
 | `chat.postMessage` | Tier 3 | ≤ triggers + summaries | Fine |
 
-No rate-limit handling is implemented in the script. If you hit limits the
-run will fail and retry on the next cron tick.
+The script surfaces Slack HTTP 429 responses with `Retry-After`. Thread reply
+polling catches that signal, delays the affected thread, and increases its
+per-thread backoff. Other Slack methods still fail fast so the next cron tick can
+retry with the persisted state.