@openhands/extensions 0.4.1 → 0.5.0

package/skills/index.js

@@ -181,11 +181,11 @@ export const SKILLS_CATALOG = [
   },
   {
     "name": "github-pr-reviewer",
-    "description": "Create an automation that reviews GitHub pull requests when they are opened or updated. Inspects the diff, changed files, tests, and existing discussion via GitHub MCP, then posts a concise review highlighting risks, security issues, missing tests, and next steps.",
+    "description": "Create an automation that reviews GitHub pull requests when a configurable trigger label is applied. Polls GitHub deterministically, starts one OpenHands review conversation per label event, inspects full repository and PR context, and posts the final review comment back to GitHub.",
     "triggers": [
       "/pr-reviewer:setup"
     ],
-    "content": "# GitHub PR Reviewer Automation\n\nCreate a cron automation that polls a GitHub repository, reviews each open\npull request exactly once, and posts the AI review as a GitHub comment.\n\nThe automation script is fully deterministic: PR discovery, state tracking,\nand deduplication are handled in Python. The LLM is only invoked to write\nthe review text for PRs not yet seen, never for orchestration.\n\n---\n\n## Prerequisites\n\n### Required secret\n\nVerify that the following secret is set in **OpenHands Settings → Secrets**:\n\n| Secret name | Token type | Minimum permissions |\n|---|---|---|\n| `GITHUB_PERSONAL_ACCESS_TOKEN` | Classic PAT | `repo` (private) or `public_repo` (public) |\n| `GITHUB_PERSONAL_ACCESS_TOKEN` | Fine-grained PAT | Pull requests: Read and Write |\n\nCheck with:\n```bash\ncurl -s https://api.github.com/user \\\n  -H \"Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN\" \\\n  | python3 -c \"import json,sys; d=json.load(sys.stdin); print(d.get('login') or d.get('message'))\"\n```\n\nIf the token is missing or invalid, inform the user and stop.\n\n---\n\n## Setup Workflow\n\nFollow these steps in order.\n\n### Step 1 — Verify GITHUB_PERSONAL_ACCESS_TOKEN\n\nRun the `curl` check above.\n\n- If absent: *\"GITHUB_PERSONAL_ACCESS_TOKEN is not set. Please add it in\n  OpenHands Settings → Secrets.\"* Stop.\n- If the API returns `{\"message\": \"Bad credentials\"}`: tell the user the\n  token is invalid and ask them to update it. Stop.\n\n### Step 2 — Collect repository\n\nAsk: *\"Which GitHub repository should be monitored?\n(Format: `owner/repo`, e.g. `myorg/backend`)\"*\n\nValidate access:\n```bash\ncurl -s \"https://api.github.com/repos/{owner}/{repo}\" \\\n  -H \"Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN\" \\\n  | python3 -c \"\nimport json, sys\nd = json.load(sys.stdin)\nif 'message' in d:\n    print('ERROR:', d['message'])\nelse:\n    print(f\\\"Accessible. Private: {d.get('private')}. Permissions: {d.get('permissions')}\\\")\n\"\n```\n\nRecord `REPO = \"{owner}/{repo}\"`.\n\n### Step 3 — Collect review tone\n\nAsk: *\"What review tone should the reviewer use?\n  1. Thorough (default) — comprehensive coverage of correctness, security, tests, style\n  2. Concise — high-signal only, skips minor style feedback\n  3. Friendly — constructive and encouraging\n(Press Enter for Thorough, or type your choice or any custom style description)\"*\n\nMap the choice to `REVIEW_TONE`:\n\n| Answer | `REVIEW_TONE` | `REVIEW_STYLE_INSTRUCTIONS` |\n|--------|--------------|------------------------------|\n| 1 / Enter | `\"thorough\"` | `\"\"` |\n| 2 | `\"concise\"` | `\"\"` |\n| 3 | `\"friendly\"` | `\"\"` |\n| Custom text (e.g. \"hostile pirate\") | `\"thorough\"` | the custom text verbatim |\n\n### Step 4 — Collect cron schedule\n\nAsk: *\"How often should the automation poll for new PRs?\n(Press Enter for the default: every 5 minutes.\nUse a cron expression for a different interval, e.g. `0 * * * *` = hourly)\"*\n\nDefault: `*/5 * * * *`.\n\nRecord as `CRON_SCHEDULE`.\n\n### Step 5 — Generate the automation script\n\nRead `scripts/main.py` from this skill's directory. Apply exactly four\nconstant substitutions near the top of the file:\n\n| Placeholder | Replace with |\n|---|---|\n| `REPO = \"owner/repo\"` | `REPO = \"{owner_repo}\"` |\n| `REVIEW_TONE = \"thorough\"` | `REVIEW_TONE = \"{review_tone}\"` |\n| `REVIEW_STYLE_INSTRUCTIONS = \"\"` | `REVIEW_STYLE_INSTRUCTIONS = \"{style_instructions}\"` |\n| `DEFAULT_OPENHANDS_URL = \"http://localhost:8000\"` | leave unchanged unless the user has a preference |\n\nWrite the customised script to a temporary build directory:\n```bash\nmkdir -p /tmp/pr-reviewer-build\n# write the customised main.py to /tmp/pr-reviewer-build/main.py\n```\n\nValidate syntax before packaging:\n```bash\npython3 -m py_compile /tmp/pr-reviewer-build/main.py && echo \"Syntax OK\"\n```\n\nFix any syntax errors before proceeding.\n\n### Step 6 — Package and upload\n\nDetermine the Automation backend URL and auth from the `<RUNTIME_SERVICES>`\nblock in your system context:\n- **OPENHANDS_HOST**: the Automation backend `url_from_agent`\n- **Auth**: `X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY`\n\n```bash\ntar -czf /tmp/pr-reviewer.tar.gz -C /tmp/pr-reviewer-build .\n\nTARBALL_PATH=$(curl -s -X POST \\\n  \"${OPENHANDS_HOST}/api/automation/v1/uploads?name=github-pr-reviewer\" \\\n  -H \"X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY\" \\\n  -H \"Content-Type: application/gzip\" \\\n  --data-binary @/tmp/pr-reviewer.tar.gz \\\n  | python3 -c \"import json,sys; print(json.load(sys.stdin)['tarball_path'])\")\n\necho \"Uploaded: $TARBALL_PATH\"\n```\n\n### Step 7 — Register the automation\n\n```bash\ncurl -s -X POST \"${OPENHANDS_HOST}/api/automation/v1\" \\\n  -H \"X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d \"{\n    \\\"name\\\": \\\"GitHub PR Reviewer: {owner}/{repo}\\\",\n    \\\"trigger\\\": {\\\"type\\\": \\\"cron\\\", \\\"schedule\\\": \\\"{cron_schedule}\\\"},\n    \\\"tarball_path\\\": \\\"$TARBALL_PATH\\\",\n    \\\"entrypoint\\\": \\\"python3 main.py\\\",\n    \\\"timeout\\\": 300\n  }\" | python3 -m json.tool\n```\n\nRecord the returned `id`.\n\n### Step 8 — Confirm\n\nTell the user:\n\n> ✅ **GitHub PR Reviewer** is running!\n>\n> - Automation ID: `{id}`\n> - Repository: `{owner}/{repo}`\n> - Review tone: `{tone}`\n> - Polling schedule: `{cron_schedule}`\n> - State file: `~/.openhands/workspaces/automation-state/github_pr_reviewer_{id}.json`\n>\n> The next cron run will discover all currently open PRs and queue reviews.\n> Each PR is reviewed exactly once; state is stored in the JSON file above.\n> To force a re-review of all PRs, delete the state file.\n\n---\n\n## Runtime Behaviour (per poll)\n\nEach cron run executes `main.py`, which:\n\n1. **Loads state** from the JSON file (see `references/state-schema.md`).\n2. **Resolves and validates `GITHUB_PERSONAL_ACCESS_TOKEN`** — aborts\n   immediately if absent or invalid.\n3. **Lists all open PRs** in the configured repository.\n4. **For each PR not yet in state**:\n   - Fetches the unified diff via the GitHub API.\n   - Skips PRs whose diff exceeds `MAX_DIFF_LINES_SKIP` (default 5000 lines)\n     and posts an explanatory comment.\n   - Truncates diffs larger than `MAX_DIFF_LINES` (default 500 lines) and\n     notes this in the prompt.\n   - Creates an OpenHands conversation with the PR metadata, diff, and\n     configured tone instructions as the initial message.\n   - Posts an acknowledgement comment on the PR with a link to the conversation.\n   - Records the PR in state with `status: \"active\"`.\n5. **For each active conversation**:\n   - Skips PRs that have been closed or merged (marks them closed silently).\n   - Checks the conversation's `execution_status`.\n   - When it reaches `idle`, `finished`, `error`, or `stuck`:\n     posts the agent's final response as a GitHub comment and marks the\n     conversation `closed`.\n6. **Saves updated state** and fires the completion callback.\n\n---\n\n## Additional Resources\n\n- **`references/state-schema.md`** — State JSON schema, field definitions,\n  and conversation lifecycle diagram.\n- **`scripts/main.py`** — The complete automation script. Customise the\n  four constants at the top before packaging.\n\n---\n\n## Troubleshooting\n\n| Symptom | Likely cause | Fix |\n|---|---|---|\n| Bot never posts reviews | `GITHUB_PERSONAL_ACCESS_TOKEN` missing or wrong scopes | Verify token; check Step 1 |\n| \"Bad credentials\" in run logs | Token expired | Rotate and update the secret |\n| 404 on repo access | Repo name wrong or no access | Re-check `owner/repo` and token permissions |\n| Same PR reviewed twice | State file deleted or corrupted | Check that the state file path is stable across runs |\n| Review never posted | Conversation stuck in `running` | Open the conversation in the OpenHands UI |\n| PR skipped silently | Diff too large | Raise `MAX_DIFF_LINES_SKIP` in the script or split the PR |"
+    "content": "# GitHub PR Reviewer Automation\n\nCreate a cron automation that watches a GitHub repository for pull requests\nwith a review trigger label, starts an OpenHands review conversation once per\nlabel event, and posts the AI review as a GitHub comment.\n\nThe automation script is deterministic: PR discovery, label-event tracking,\nstate persistence, stale-result suppression, and GitHub comment posting are\nhandled in Python. The LLM is invoked only for the review itself.\n\n---\n\n## Prerequisites\n\n### Required secret\n\nVerify that the following secret is set in **OpenHands Settings -> Secrets**:\n\n| Secret name | Token type | Minimum permissions |\n|---|---|---|\n| `GITHUB_PERSONAL_ACCESS_TOKEN` | Classic PAT | `repo` for private repos or `public_repo` for public repos |\n| `GITHUB_PERSONAL_ACCESS_TOKEN` | Fine-grained PAT | Contents: Read, Metadata: Read, Pull requests: Read, Issues: Read and Write |\n\nCheck with:\n```bash\ncurl -s https://api.github.com/user \\\n  -H \"Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN\" \\\n  | python3 -c \"import json,sys; d=json.load(sys.stdin); print(d.get('login') or d.get('message'))\"\n```\n\nIf the token is missing or invalid, inform the user and stop.\n\n---\n\n## Setup Workflow\n\nFollow these steps in order.\n\n### Step 1 - Verify `GITHUB_PERSONAL_ACCESS_TOKEN`\n\nRun the `curl` check above.\n\n- If absent: *\"GITHUB_PERSONAL_ACCESS_TOKEN is not set. Please add it in\n  OpenHands Settings -> Secrets.\"* Stop.\n- If the API returns `{\"message\": \"Bad credentials\"}`: tell the user the\n  token is invalid and ask them to update it. Stop.\n\n### Step 2 - Collect repository\n\nAsk: *\"Which GitHub repository should be monitored?\n(Format: `owner/repo`, e.g. `myorg/backend`)\"*\n\nValidate access:\n```bash\ncurl -s \"https://api.github.com/repos/{owner}/{repo}\" \\\n  -H \"Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN\" \\\n  | python3 -c \"\nimport json, sys\nd = json.load(sys.stdin)\nif 'message' in d:\n    print('ERROR:', d['message'])\nelse:\n    print(f\\\"Accessible. Private: {d.get('private')}. Permissions: {d.get('permissions')}\\\")\n\"\n```\n\nRecord `REPO = \"{owner}/{repo}\"`.\n\n### Step 3 - Collect trigger label\n\nAsk: *\"Which PR label should trigger a review?\n(Press Enter for the default: `openhands-review`.)\"*\n\nRecord the answer as `TRIGGER_LABEL`. If the label does not exist yet, tell the\nuser that GitHub will still record the event once the label is created and\napplied to a PR.\n\nThe automation reviews a PR when it sees the latest matching `labeled` event for\nthat label. To request another review later, remove and re-apply the label.\n\n### Step 4 - Collect review tone\n\nAsk: *\"What review tone should the reviewer use?\n  1. Thorough (default) - comprehensive coverage of correctness, security, tests, style\n  2. Concise - high-signal only, skips minor style feedback\n  3. Friendly - constructive and encouraging\n(Press Enter for Thorough, or type your choice or any custom style description)\"*\n\nMap the choice to `REVIEW_TONE`:\n\n| Answer | `REVIEW_TONE` | `REVIEW_STYLE_INSTRUCTIONS` |\n|---|---|---|\n| 1 / Enter | `\"thorough\"` | `\"\"` |\n| 2 | `\"concise\"` | `\"\"` |\n| 3 | `\"friendly\"` | `\"\"` |\n| Custom text, e.g. `strict but kind` | `\"thorough\"` | the custom text verbatim |\n\n### Step 5 - Collect cron schedule\n\nAsk: *\"How often should the automation poll for labeled PRs?\n(Press Enter for the default: every 5 minutes.\nUse a cron expression for a different interval, e.g. `0 * * * *` = hourly)\"*\n\nDefault: `*/5 * * * *`.\n\nRecord as `CRON_SCHEDULE`.\n\n### Step 6 - Generate the automation script\n\nRead `scripts/main.py` from this skill's directory. Apply exactly five constant\nsubstitutions near the top of the file:\n\n| Placeholder | Replace with |\n|---|---|\n| `REPO = \"owner/repo\"` | `REPO = \"{owner_repo}\"` |\n| `TRIGGER_LABEL = \"openhands-review\"` | `TRIGGER_LABEL = \"{trigger_label}\"` |\n| `REVIEW_TONE = \"thorough\"` | `REVIEW_TONE = \"{review_tone}\"` |\n| `REVIEW_STYLE_INSTRUCTIONS = \"\"` | `REVIEW_STYLE_INSTRUCTIONS = \"{style_instructions}\"` |\n| `DEFAULT_OPENHANDS_URL = \"http://localhost:8000\"` | leave unchanged unless the user has a preference |\n\nUse a safe string writer such as `json.dumps(value)` when inserting user-provided\nrepository names, labels, or style instructions into Python string literals.\n\nWrite the customized script to a temporary build directory:\n```bash\nmkdir -p /tmp/pr-reviewer-build\n# write the customized main.py to /tmp/pr-reviewer-build/main.py\n```\n\nValidate syntax before packaging:\n```bash\npython3 -m py_compile /tmp/pr-reviewer-build/main.py && echo \"Syntax OK\"\n```\n\nFix any syntax errors before proceeding.\n\n### Step 7 - Package and upload\n\nDetermine the Automation backend URL and auth from the `<RUNTIME_SERVICES>`\nblock in your system context:\n- **OPENHANDS_HOST**: the Automation backend `url_from_agent`\n- **Auth**: `X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY`\n\n```bash\ntar -czf /tmp/pr-reviewer.tar.gz -C /tmp/pr-reviewer-build .\n\nTARBALL_PATH=$(curl -s -X POST \\\n  \"${OPENHANDS_HOST}/api/automation/v1/uploads?name=github-pr-reviewer\" \\\n  -H \"X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY\" \\\n  -H \"Content-Type: application/gzip\" \\\n  --data-binary @/tmp/pr-reviewer.tar.gz \\\n  | python3 -c \"import json,sys; print(json.load(sys.stdin)['tarball_path'])\")\n\necho \"Uploaded: $TARBALL_PATH\"\n```\n\n### Step 8 - Register the automation\n\n```bash\ncurl -s -X POST \"${OPENHANDS_HOST}/api/automation/v1\" \\\n  -H \"X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d \"{\n    \\\"name\\\": \\\"GitHub PR Reviewer: {owner}/{repo} label {trigger_label}\\\",\n    \\\"trigger\\\": {\\\"type\\\": \\\"cron\\\", \\\"schedule\\\": \\\"{cron_schedule}\\\"},\n    \\\"tarball_path\\\": \\\"$TARBALL_PATH\\\",\n    \\\"entrypoint\\\": \\\"python3 main.py\\\",\n    \\\"timeout\\\": 300\n  }\" | python3 -m json.tool\n```\n\nRecord the returned `id`.\n\n### Step 9 - Confirm\n\nTell the user:\n\n> ✅ **GitHub PR Reviewer** is running!\n>\n> - Automation ID: `{id}`\n> - Repository: `{owner}/{repo}`\n> - Trigger label: `{trigger_label}`\n> - Review tone: `{tone}`\n> - Polling schedule: `{cron_schedule}`\n> - State file: `~/.openhands/workspaces/automation-state/github_pr_reviewer_label_event_{id}.json`\n>\n> Apply the `{trigger_label}` label to a pull request to queue a review. Each\n> label event is processed once. To request another review, remove and re-apply\n> the label.\n\n---\n\n## Runtime Behaviour (per poll)\n\nEach cron run executes `main.py`, which:\n\n1. Loads state from the JSON file (see `references/state-schema.md`).\n2. Resolves and validates `GITHUB_PERSONAL_ACCESS_TOKEN` and repository access.\n3. Lists open PRs, newest-updated first.\n4. For each open PR carrying `TRIGGER_LABEL`:\n   - Refetches current PR metadata to avoid acting on stale list data.\n   - Finds the latest matching GitHub `labeled` issue event.\n   - Skips the event if it has already been tracked.\n   - Starts an OpenHands conversation with a review prompt that includes PR\n     metadata, the exact head SHA, label event details, and instructions to\n     clone the repo, inspect PR discussion, review comments, changed files,\n     diff, and surrounding code.\n   - Posts an acknowledgement comment with the label event, head SHA, and\n     conversation link.\n   - Records the label-event review in state with `status: \"active\"`.\n5. For each active review conversation:\n   - Marks it closed without posting if the PR has closed or merged.\n   - Suppresses stale results if the PR head SHA changed after the review was\n     queued.\n   - When the conversation reaches `idle`, `finished`, `error`, or `stuck`,\n     posts the agent's final response as a GitHub comment and marks the review\n     closed.\n6. Saves state atomically and fires the completion callback.\n\n---\n\n## Additional Resources\n\n- **`references/state-schema.md`** - State JSON schema, field definitions, and\n  review lifecycle diagram.\n- **`scripts/main.py`** - The complete automation script. Customize the five\n  constants at the top before packaging.\n\n---\n\n## Troubleshooting\n\n| Symptom | Likely cause | Fix |\n|---|---|---|\n| Bot never queues reviews | Trigger label not present or no matching `labeled` event | Apply the configured label to the PR |\n| \"Bad credentials\" in run logs | Token expired | Rotate and update `GITHUB_PERSONAL_ACCESS_TOKEN` |\n| 404 on repo access | Repo name wrong or no access | Re-check `owner/repo` and token permissions |\n| Same PR not reviewed after new commits | Label event was already processed | Remove and re-apply the trigger label |\n| Review result never posts | Conversation still running or stuck | Open the conversation link from the acknowledgement comment |\n| Stale review suppressed | PR head SHA changed while the agent was reviewing | Re-apply the trigger label after the latest commit |"
   },
   {
     "name": "github-repo-monitor",
@@ -398,7 +398,7 @@ export const SKILLS_CATALOG = [
     "triggers": [
       "/slack-monitor:poll"
     ],
-    "content": "# Slack Channel Monitor\n\nCreate a cron automation that polls up to 10 Slack channels every minute.\nWhen a message containing the **trigger phrase** (default: `@openhands`) is\ndetected it:\n\n1. Adds a 👀 reaction to the triggering message.\n2. Opens an OpenHands conversation with the message and recent channel context.\n3. Posts a reply in the Slack thread with a link to the conversation.\n\nOn every subsequent run:\n- Replies in the thread are forwarded to the running conversation.\n- When the conversation finishes (or errors), the agent's final response is\n  posted back to the Slack thread.\n\n> **Local mode only.** This automation targets the local OpenHands setup\n> (`dev:automation` stack). A cloud/webhook-based variant is out of scope here.\n\n---\n\n## Prerequisites\n\n### Required secrets\n\nVerify that at least one of the following secrets is set in\n**OpenHands Settings → Secrets** before proceeding:\n\n| Secret name | Token type | Minimum scopes |\n|---|---|---|\n| `SLACK_BOT_TOKEN` | Bot (`xoxb-…`) | `channels:history`, `channels:read`, `reactions:write`, `chat:write` |\n| `SLACK_USER_TOKEN` | User (`xoxp-…`) | Same as bot, plus `search:read` for multi-channel efficiency |\n\nCheck with:\n```bash\n# For bot token:\ncurl -s https://slack.com/api/auth.test -H \"Authorization: Bearer $SLACK_BOT_TOKEN\" \\\n  | python3 -c \"import json,sys; d=json.load(sys.stdin); print('ok' if d.get('ok') else d.get('error'))\"\n\n# For user token:\ncurl -s https://slack.com/api/auth.test -H \"Authorization: Bearer $SLACK_USER_TOKEN\" \\\n  | python3 -c \"import json,sys; d=json.load(sys.stdin); print('ok' if d.get('ok') else d.get('error'))\"\n```\n\nIf neither token is present, inform the user and stop  -  the automation cannot\nfunction without Slack credentials.\n\n### Optional secret\n\n| Secret name | Default | Purpose |\n|---|---|---|\n| `OPENHANDS_URL` | `http://localhost:8000` | Base URL used to build conversation links posted in Slack |\n\n---\n\n## Setup Workflow\n\nFollow these steps in order.\n\n### Step 1  -  Collect channels\n\nAsk the user: *\"Which Slack channels should be monitored? You can provide\nchannel names (e.g. `#general`) or IDs (e.g. `C0123456789`).\"*\n\n**If the user provides channel names**, resolve them to IDs:\n\n```bash\nSLACK_TOKEN=\"${SLACK_BOT_TOKEN:-$SLACK_USER_TOKEN}\"\ncurl -s \"https://slack.com/api/conversations.list?types=public_channel,private_channel&limit=200&exclude_archived=true\" \\\n  -H \"Authorization: Bearer $SLACK_TOKEN\" \\\n  | python3 -c \"\nimport json, sys\ndata = json.load(sys.stdin)\nif not data.get('ok'):\n    print('ERROR:', data.get('error'))\n    exit(1)\nnames = set(n.lstrip('#') for n in ['CHANNEL_NAMES_HERE'.split(',')])\nfor ch in data.get('channels', []):\n    if ch['name'] in names:\n        print(f\\\"{ch['name']} → {ch['id']}\\\")\n\"\n```\n\nReplace `CHANNEL_NAMES_HERE` with the comma-separated names the user provided.\n\n**If `conversations.list` returns `missing_scope` or `not_authed`:**\nInform the user: *\"The token doesn't have permission to list channels. Please\nprovide the channel IDs directly (right-click a channel in Slack → Copy link  - \nthe last path segment starting with `C` is the ID).\"*\n\n**If the bot token lacks `channels:read`** for private channels, the user can\neither invite the bot first (`/invite @botname`) or switch to a user token.\n\nCollect up to 10 channel IDs. Record them as a Python list literal, e.g.:\n```python\n[\"C0123456789\", \"C9876543210\"]\n```\n\n### Step 2  -  Collect trigger phrase\n\nAsk the user: *\"What trigger phrase should OpenHands respond to?\n(Press Enter to use the default: `@openhands`)\"*\n\nAccepted values: any non-empty string unlikely to appear accidentally, e.g.\n`@openhands`, `jazz hands`, `take-me-to-funky-town`.\n\n### Step 3  -  Generate the automation script\n\nRead `scripts/main.py` from this skill's directory and **copy it verbatim**.\nApply exactly three constant substitutions near the top of the file:\n\n> **Do not reimplement, simplify, or hand-write a replacement script.**\n> The template already contains the correct secret-loading, state-path,\n> conversation-creation, and context-forwarding logic. Only the three\n> configuration constants below should change unless syntax validation fails.\n\n| Placeholder | Replace with |\n|---|---|\n| `TRIGGER_PHRASE = \"@openhands\"` | `TRIGGER_PHRASE = \"{user_phrase}\"` |\n| `CHANNEL_IDS: list[str] = []` | `CHANNEL_IDS: list[str] = {channel_id_list}` |\n| `DEFAULT_OPENHANDS_URL = \"http://localhost:8000\"` | `DEFAULT_OPENHANDS_URL = \"{url}\"` (keep default if user has no preference) |\n\nWrite the customised script to a temporary directory:\n```bash\nmkdir -p /tmp/slack-monitor-build\n# copy scripts/main.py to /tmp/slack-monitor-build/main.py\n# then replace only the three constants above\n```\n\nValidate syntax before packaging:\n```bash\npython3 -m py_compile /tmp/slack-monitor-build/main.py && echo \"Syntax OK\"\n```\n\nThen run a quick integrity check to confirm the template structure is still\npresent and only the configuration block was customised:\n```bash\ngrep -n 'TRIGGER_PHRASE = \"' /tmp/slack-monitor-build/main.py\ngrep -n 'CHANNEL_IDS: list\\[str\\] =' /tmp/slack-monitor-build/main.py\ngrep -n 'DEFAULT_OPENHANDS_URL = \"' /tmp/slack-monitor-build/main.py\ngrep -n 'def get_secret' /tmp/slack-monitor-build/main.py\ngrep -n 'def _state_file_path' /tmp/slack-monitor-build/main.py\ngrep -n 'def create_conversation' /tmp/slack-monitor-build/main.py\n```\n\nIf any of those checks fail, stop and re-copy the template instead of trying to\nrepair a hand-written variant.\n\n### Step 4  -  Package and upload\n\nDetermine the Automation backend URL and auth from the `<RUNTIME_SERVICES>`\nblock in your system context:\n- Use the **Automation backend** `url_from_agent` as `OPENHANDS_HOST`\n- Auth: `X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY`\n\nIf no Automation backend is listed in `<RUNTIME_SERVICES>`, stop and tell\nthe user to start the full automation stack.\n\n```bash\ntar -czf /tmp/slack-monitor.tar.gz -C /tmp/slack-monitor-build .\n\n# OPENHANDS_HOST: read from <RUNTIME_SERVICES> Automation backend url_from_agent\nOPENHANDS_HOST=\"<automation-url-from-runtime-services>\"\n\nTARBALL_PATH=$(curl -s -X POST \\\n  \"${OPENHANDS_HOST}/api/automation/v1/uploads?name=slack-channel-monitor\" \\\n  -H \"X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY\" \\\n  -H \"Content-Type: application/gzip\" \\\n  --data-binary @/tmp/slack-monitor.tar.gz \\\n  | python3 -c \"import json,sys; print(json.load(sys.stdin)['tarball_path'])\")\n\necho \"Uploaded: $TARBALL_PATH\"\n```\n\nIf the upload fails with a size error, the tarball must be under 1 MB.\n`main.py` is under 15 KB so this should never trigger.\n\n### Step 5  -  Create the automation\n\n```bash\ncurl -s -X POST \"${OPENHANDS_HOST}/api/automation/v1\" \\\n  -H \"X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d \"{\n    \\\"name\\\": \\\"Slack Channel Monitor\\\",\n    \\\"trigger\\\": {\\\"type\\\": \\\"cron\\\", \\\"schedule\\\": \\\"* * * * *\\\"},\n    \\\"tarball_path\\\": \\\"$TARBALL_PATH\\\",\n    \\\"entrypoint\\\": \\\"python3 main.py\\\",\n    \\\"timeout\\\": 55\n  }\" | python3 -m json.tool\n```\n\nA 55-second timeout keeps runs well within the 60-second cron window.\n\nRecord the returned `id`  -  share it with the user as confirmation.\n\n### Step 6  -  Confirm\n\nTell the user:\n\n> ✅ **Slack Channel Monitor** is running!\n>\n> - Automation ID: `{id}`\n> - Channels: `{channel list}`\n> - Trigger phrase: `{phrase}`\n> - Polling every minute via cron `* * * * *`\n> - State file: `~/.openhands/workspaces/automation-state/slack_poller_{id}.json`\n>\n> Send a message containing `{phrase}` in any monitored channel to test it.\n> The bot will react with 👀 and reply with a link to the new conversation.\n\n---\n\n## Runtime Behaviour (per poll)\n\nEach cron run executes `main.py`, which runs **10 polling iterations** (every\n5 seconds) within the 55-second timeout window. Each iteration:\n\n1. **Loads state** from the JSON file (see `references/state-schema.md`).\n2. **Resolves the Slack token**  -  checks `SLACK_USER_TOKEN` then `SLACK_BOT_TOKEN`.\n3. **Fetches new messages:**\n   - User token + `search:read` + > 1 channel → single `search.messages` call\n     (searches for the trigger phrase across all channels).\n   - Otherwise → one `conversations.history` call per channel.\n4. **Fetches thread replies**  -  one `conversations.replies` call per tracked thread.\n5. **Processes messages** in chronological order:\n   - Skips messages already in `processed_ts` (dedup across the overlap window).\n   - Skips bot messages and any `ts` in `bot_message_ts`.\n   - Reply in a tracked thread (active **or** closed) → forwards to the existing\n     conversation; re-opens closed conversations automatically.\n   - Contains trigger phrase → 👀 reaction, create conversation, post link.\n     - Thread replies: agent receives full thread history for context.\n     - Root messages: agent receives the trigger text only.\n6. **Checks conversation statuses**  -  for each active conversation where\n   `time.time() - last_activity > 15 s`:\n   - If status is `idle`, `finished`, `error`, or `stuck` → fetch the agent's\n     final response via `/api/conversations/{id}/agent_final_response` and post\n     it to the Slack thread. Mark conversation `closed`.\n7. **Advances `last_poll`** to `now - 10 s` (overlap window prevents boundary\n   races). If a conversation creation failed, pins `last_poll` further back to\n   retry on the next iteration.\n8. **Saves state** (including `processed_ts`) and continues to the next iteration.\n9. After all iterations, fires the completion callback.\n\nDebug output is written to both stdout and a persistent log at:\n```\n{WORKSPACE_BASE_ROOT}/automation-state/slack_poller_debug.log\n```\n\n---\n\n## Additional Resources\n\n### Reference Files\n\n- **`references/slack-api.md`**  -  Slack token types, required scopes, API\n  endpoint reference, rate limits, and common error codes.\n- **`references/state-schema.md`**  -  State JSON schema, field definitions,\n  example file, and conversation lifecycle diagram.\n\n### Script Template\n\n- **`scripts/main.py`**  -  The complete automation script. Customise the three\n  constants at the top (`TRIGGER_PHRASE`, `CHANNEL_IDS`, `DEFAULT_OPENHANDS_URL`)\n  before packaging.\n\n---\n\n## Troubleshooting\n\n| Symptom | Likely cause | Fix |\n|---|---|---|\n| Bot doesn't react to messages | Token missing or bot not in channel | Verify token with `auth.test`; `/invite @botname` |\n| `not_in_channel` error in run logs | Bot token used but bot not a member | Invite bot or switch to user token |\n| `missing_scope` error | Token lacks required scopes | Re-install Slack app with correct scopes (see `references/slack-api.md`) |\n| No messages detected | `last_poll` timestamp is in the future | Delete the state file to reset; it will be recreated on next run |\n| Conversation link 404 | `OPENHANDS_URL` points to wrong host | Set the `OPENHANDS_URL` secret to the correct base URL |\n| Summary never posted | Conversation stuck in `running` state | Check conversation in the OpenHands UI; the agent may need intervention |\n| Duplicate conversations created | `processed_ts` state missing or corrupted | Delete the state file to reset; dedup will rebuild on next run |\n| Trigger message processed on each cron run | State file deleted between runs | Ensure `automation-state/` directory is persistent across runs |\n| Debug info needed | Need detailed per-message trace | Check `{WORKSPACE_BASE_ROOT}/automation-state/slack_poller_debug.log` |"
+    "content": "# Slack Channel Monitor\n\nCreate a cron automation that polls up to 10 Slack channels every minute.\nWhen a message containing the **trigger phrase** (default: `@openhands`) is\ndetected it:\n\n1. Adds a 👀 reaction to the triggering message.\n2. Opens an OpenHands conversation with the message and recent channel context.\n3. Posts a reply in the Slack thread with a link to the conversation.\n\nOn every subsequent run:\n- New Slack thread replies are forwarded only when they contain the trigger\n  phrase, so unrelated conversation in the thread is ignored.\n- When the conversation finishes (or errors), the agent's final response is\n  posted back to the Slack thread.\n- Completed conversations stay in a short follow-up watch window, allowing\n  triggered Slack replies to continue the same OpenHands conversation.\n\n> **Local mode only.** This automation targets the local OpenHands setup\n> (`dev:automation` stack). A cloud/webhook-based variant is out of scope here.\n\n---\n\n## Prerequisites\n\n### Required secrets\n\nVerify that at least one of the following secrets is set in\n**OpenHands Settings → Secrets** before proceeding:\n\n| Secret name | Token type | Minimum scopes |\n|---|---|---|\n| `SLACK_BOT_TOKEN` | Bot (`xoxb-…`) | `channels:history`, `channels:read`, `reactions:write`, `chat:write` |\n| `SLACK_USER_TOKEN` | User (`xoxp-…`) | Same as bot, plus `search:read` for multi-channel efficiency |\n\nCheck with:\n```bash\n# For bot token:\ncurl -s https://slack.com/api/auth.test -H \"Authorization: Bearer $SLACK_BOT_TOKEN\" \\\n  | python3 -c \"import json,sys; d=json.load(sys.stdin); print('ok' if d.get('ok') else d.get('error'))\"\n\n# For user token:\ncurl -s https://slack.com/api/auth.test -H \"Authorization: Bearer $SLACK_USER_TOKEN\" \\\n  | python3 -c \"import json,sys; d=json.load(sys.stdin); print('ok' if d.get('ok') else d.get('error'))\"\n```\n\nIf neither token is present, inform the user and stop  -  the automation cannot\nfunction without Slack credentials.\n\n### Optional secret\n\n| Secret name | Default | Purpose |\n|---|---|---|\n| `OPENHANDS_URL` | `http://localhost:8000` | Base URL used to build conversation links posted in Slack |\n\n---\n\n## Setup Workflow\n\nFollow these steps in order.\n\n### Step 1  -  Collect channels\n\nAsk the user: *\"Which Slack channels should be monitored? You can provide\nchannel names (e.g. `#general`) or IDs (e.g. `C0123456789`).\"*\n\n**If the user provides channel names**, resolve them to IDs:\n\n```bash\nSLACK_TOKEN=\"${SLACK_BOT_TOKEN:-$SLACK_USER_TOKEN}\"\ncurl -s \"https://slack.com/api/conversations.list?types=public_channel,private_channel&limit=200&exclude_archived=true\" \\\n  -H \"Authorization: Bearer $SLACK_TOKEN\" \\\n  | python3 -c \"\nimport json, sys\ndata = json.load(sys.stdin)\nif not data.get('ok'):\n    print('ERROR:', data.get('error'))\n    exit(1)\nnames = set(n.lstrip('#') for n in ['CHANNEL_NAMES_HERE'.split(',')])\nfor ch in data.get('channels', []):\n    if ch['name'] in names:\n        print(f\\\"{ch['name']} → {ch['id']}\\\")\n\"\n```\n\nReplace `CHANNEL_NAMES_HERE` with the comma-separated names the user provided.\n\n**If `conversations.list` returns `missing_scope` or `not_authed`:**\nInform the user: *\"The token doesn't have permission to list channels. Please\nprovide the channel IDs directly (right-click a channel in Slack → Copy link  - \nthe last path segment starting with `C` is the ID).\"*\n\n**If the bot token lacks `channels:read`** for private channels, the user can\neither invite the bot first (`/invite @botname`) or switch to a user token.\n\nCollect up to 10 channel IDs. Record them as a Python list literal, e.g.:\n```python\n[\"C0123456789\", \"C9876543210\"]\n```\n\n### Step 2  -  Collect trigger phrase\n\nAsk the user: *\"What trigger phrase should OpenHands respond to?\n(Press Enter to use the default: `@openhands`)\"*\n\nAccepted values: any non-empty string unlikely to appear accidentally, e.g.\n`@openhands`, `jazz hands`, `take-me-to-funky-town`.\n\n### Step 3  -  Generate the automation script\n\nRead `scripts/main.py` from this skill's directory and **copy it verbatim**.\nApply exactly three constant substitutions near the top of the file:\n\n> **Do not reimplement, simplify, or hand-write a replacement script.**\n> The template already contains the correct secret-loading, state-path,\n> conversation-creation, and context-forwarding logic. Only the three\n> configuration constants below should change unless syntax validation fails.\n\n| Placeholder | Replace with |\n|---|---|\n| `TRIGGER_PHRASE = \"@openhands\"` | `TRIGGER_PHRASE = \"{user_phrase}\"` |\n| `CHANNEL_IDS: list[str] = []` | `CHANNEL_IDS: list[str] = {channel_id_list}` |\n| `DEFAULT_OPENHANDS_URL = \"http://localhost:8000\"` | `DEFAULT_OPENHANDS_URL = \"{url}\"` (keep default if user has no preference) |\n\nWrite the customised script to a temporary directory:\n```bash\nmkdir -p /tmp/slack-monitor-build\n# copy scripts/main.py to /tmp/slack-monitor-build/main.py\n# then replace only the three constants above\n```\n\nValidate syntax before packaging:\n```bash\npython3 -m py_compile /tmp/slack-monitor-build/main.py && echo \"Syntax OK\"\n```\n\nThen run a quick integrity check to confirm the template structure is still\npresent and only the configuration block was customised:\n```bash\ngrep -n 'TRIGGER_PHRASE = \"' /tmp/slack-monitor-build/main.py\ngrep -n 'CHANNEL_IDS: list\\[str\\] =' /tmp/slack-monitor-build/main.py\ngrep -n 'DEFAULT_OPENHANDS_URL = \"' /tmp/slack-monitor-build/main.py\ngrep -n 'def get_secret' /tmp/slack-monitor-build/main.py\ngrep -n 'def _state_file_path' /tmp/slack-monitor-build/main.py\ngrep -n 'def create_conversation' /tmp/slack-monitor-build/main.py\n```\n\nIf any of those checks fail, stop and re-copy the template instead of trying to\nrepair a hand-written variant.\n\n### Step 4  -  Package and upload\n\nDetermine the Automation backend URL and auth from the `<RUNTIME_SERVICES>`\nblock in your system context:\n- Use the **Automation backend** `url_from_agent` as `OPENHANDS_HOST`\n- Auth: `X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY`\n\nIf no Automation backend is listed in `<RUNTIME_SERVICES>`, stop and tell\nthe user to start the full automation stack.\n\n```bash\ntar -czf /tmp/slack-monitor.tar.gz -C /tmp/slack-monitor-build .\n\n# OPENHANDS_HOST: read from <RUNTIME_SERVICES> Automation backend url_from_agent\nOPENHANDS_HOST=\"<automation-url-from-runtime-services>\"\n\nTARBALL_PATH=$(curl -s -X POST \\\n  \"${OPENHANDS_HOST}/api/automation/v1/uploads?name=slack-channel-monitor\" \\\n  -H \"X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY\" \\\n  -H \"Content-Type: application/gzip\" \\\n  --data-binary @/tmp/slack-monitor.tar.gz \\\n  | python3 -c \"import json,sys; print(json.load(sys.stdin)['tarball_path'])\")\n\necho \"Uploaded: $TARBALL_PATH\"\n```\n\nIf the upload fails with a size error, the tarball must be under 1 MB.\n`main.py` is under 15 KB so this should never trigger.\n\n### Step 5  -  Create the automation\n\n```bash\ncurl -s -X POST \"${OPENHANDS_HOST}/api/automation/v1\" \\\n  -H \"X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d \"{\n    \\\"name\\\": \\\"Slack Channel Monitor\\\",\n    \\\"trigger\\\": {\\\"type\\\": \\\"cron\\\", \\\"schedule\\\": \\\"* * * * *\\\"},\n    \\\"tarball_path\\\": \\\"$TARBALL_PATH\\\",\n    \\\"entrypoint\\\": \\\"python3 main.py\\\",\n    \\\"timeout\\\": 55\n  }\" | python3 -m json.tool\n```\n\nA 55-second timeout keeps runs well within the 60-second cron window.\n\nRecord the returned `id`  -  share it with the user as confirmation.\n\n### Step 6  -  Confirm\n\nTell the user:\n\n> ✅ **Slack Channel Monitor** is running!\n>\n> - Automation ID: `{id}`\n> - Channels: `{channel list}`\n> - Trigger phrase: `{phrase}`\n> - Polling every minute via cron `* * * * *`\n> - State file: `~/.openhands/workspaces/automation-state/slack_poller_{id}.json`\n>\n> Send a message containing `{phrase}` in any monitored channel to test it.\n> The bot will react with 👀 and reply with a link to the new conversation.\n\n---\n\n## Runtime Behaviour (per poll)\n\nEach cron run executes `main.py`, which runs **10 polling iterations** (every\n5 seconds) within the 55-second timeout window. Each iteration:\n\n1. **Loads state** from the JSON file (see `references/state-schema.md`).\n2. **Resolves the Slack token**  -  checks `SLACK_USER_TOKEN` then `SLACK_BOT_TOKEN`.\n3. **Fetches new messages:**\n   - User token + `search:read` + > 1 channel → single `search.messages` call\n     (searches for the trigger phrase across all channels).\n   - Otherwise → one `conversations.history` call per channel.\n4. **Fetches due thread replies**  -  polls at most one tracked thread per\n   iteration using per-thread exponential backoff to stay within Slack rate\n   limits.\n5. **Processes messages** in chronological order:\n   - Skips messages already in `processed_ts` (dedup across the overlap window).\n   - Skips bot messages and any `ts` in `bot_message_ts`.\n   - Reply in a tracked thread whose text contains the trigger phrase → forwards\n     a follow-up request to the existing conversation and resets the follow-up\n     watch window. Replies without the trigger phrase are marked processed and\n     ignored.\n   - Contains trigger phrase outside a tracked conversation → 👀 reaction, create\n     a new conversation, post link.\n     - Thread replies: agent receives full thread history for context.\n     - Root messages: agent receives the trigger text only.\n6. **Checks conversation statuses**  -  for each active conversation where\n   `time.time() - last_activity > 15 s`:\n   - If status is `idle`, `finished`, `error`, or `stuck` → fetch the agent's\n     final response via `/api/conversations/{id}/agent_final_response` and post\n     it to the Slack thread. Mark the record `watching` for five minutes so\n     triggered follow-up replies can continue the same conversation.\n7. **Advances `last_poll`** to `now - 10 s` (overlap window prevents boundary\n   races). If a conversation creation failed, pins `last_poll` further back to\n   retry on the next iteration.\n8. **Saves state** (including `processed_ts`) and continues to the next iteration.\n9. After all iterations, fires the completion callback.\n\nDebug output is written to both stdout and a persistent log at:\n```\n{WORKSPACE_BASE_ROOT}/automation-state/slack_poller_debug.log\n```\n\n---\n\n## Additional Resources\n\n### Reference Files\n\n- **`references/slack-api.md`**  -  Slack token types, required scopes, API\n  endpoint reference, rate limits, and common error codes.\n- **`references/state-schema.md`**  -  State JSON schema, field definitions,\n  example file, and conversation lifecycle diagram.\n\n### Script Template\n\n- **`scripts/main.py`**  -  The complete automation script. Customise the three\n  constants at the top (`TRIGGER_PHRASE`, `CHANNEL_IDS`, `DEFAULT_OPENHANDS_URL`)\n  before packaging.\n\n---\n\n## Troubleshooting\n\n| Symptom | Likely cause | Fix |\n|---|---|---|\n| Bot doesn't react to messages | Token missing or bot not in channel | Verify token with `auth.test`; `/invite @botname` |\n| `not_in_channel` error in run logs | Bot token used but bot not a member | Invite bot or switch to user token |\n| `missing_scope` error | Token lacks required scopes | Re-install Slack app with correct scopes (see `references/slack-api.md`) |\n| No messages detected | `last_poll` timestamp is in the future | Delete the state file to reset; it will be recreated on next run |\n| Conversation link 404 | `OPENHANDS_URL` points to wrong host | Set the `OPENHANDS_URL` secret to the correct base URL |\n| Summary never posted | Conversation stuck in `running` state | Check conversation in the OpenHands UI; the agent may need intervention |\n| Duplicate conversations created | `processed_ts` state missing or corrupted | Delete the state file to reset; dedup will rebuild on next run |\n| Trigger message processed on each cron run | State file deleted between runs | Ensure `automation-state/` directory is persistent across runs |\n| Debug info needed | Need detailed per-message trace | Check `{WORKSPACE_BASE_ROOT}/automation-state/slack_poller_debug.log` |"
   },
   {
     "name": "slack-standup-digest",

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
+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 back to
-   Slack when the conversation completes
+   Slack when the conversation completes, 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,26 @@ 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. 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.

package/skills/slack-channel-monitor/references/state-schema.md

@@ -52,7 +52,7 @@ variable (field `automation_id`).
 
 ## `conversations` Map
 
-Key: `"{channel_id}:{thread_root_ts}"`  -  uniquely identifies a Slack thread.
+Key: `"{channel_id}:{thread_root_ts}"` - uniquely identifies a Slack thread.
 
 Value: **ConversationRecord**
 
@@ -61,14 +61,25 @@ Value: **ConversationRecord**
   // Required fields
   "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
                                       // OpenHands conversation UUID
-  "channel_id":      "C0123456789",  // Slack channel ID
+  "channel_id":      "C0123456789", // Slack channel ID
   "thread_ts":       "1716576000.000100",
                                       // Slack thread root timestamp
                                       // (= msg_ts for top-level trigger messages)
-  "status":          "active",        // "active" | "closed"
-  "last_activity":   1716576060.0,    // float Unix timestamp of the last time the
-                                      // script sent a message to this conversation
-                                      // (creation time, or time a reply was forwarded)
+  "status":          "active",      // "active" | "watching" | "closed"
+  "last_activity":   1716576060.0,   // float Unix timestamp of the last time the
+                                      // script created, resumed, or summarized the
+                                      // OpenHands conversation
+
+  // Follow-up polling fields
+  "last_seen_reply_ts": "1716576000.000100",
+                                      // newest Slack reply ts observed for this thread
+  "reply_poll_backoff_seconds": 5,   // current per-thread conversations.replies backoff
+  "next_reply_poll_at": 1716576065.0,// next Unix timestamp when replies may be polled
+  "watch_until": 1716576360.0,       // follow-up watch expiry for completed conversations
+
+  // Present after expiry
+  "closed_reason": "followup_watch_expired",
+  "closed_at": 1716576360.0
 }
 ```
 
@@ -76,13 +87,13 @@ Value: **ConversationRecord**
 
 | Value | Meaning |
 |-------|---------|
-| `active` | Conversation is running or awaiting more input; replies will be forwarded |
-| `closed` | Summary has been posted to Slack; no further processing |
+| `active` | Conversation is running or awaiting completion; triggered replies are forwarded to it |
+| `watching` | A summary has been posted and the thread remains open briefly for triggered follow-ups |
+| `closed` | The follow-up watch expired; future triggered replies create a new conversation |
 
-Closed conversations are retained in the map indefinitely (the map stays small
-since there are < 10 channels and the trigger rate is typically low). If the
-map grows unexpectedly, closed entries older than a configurable TTL can be
-pruned.
+`watching` records use `watch_until` to avoid keeping every completed thread hot
+forever. Quiet watched threads use exponential backoff for `conversations.replies`
+polling, and each automation iteration polls at most one due thread.
 
 ---
 
@@ -109,9 +120,9 @@ exactly `now`, messages near the boundary are re-fetched on the next iteration.
 re-fetched messages from being processed twice (e.g., triggering a duplicate
 conversation or forwarding the same reply multiple times).
 
-Entries are added when a message is either skipped (not human, already handled)
-or successfully processed (trigger detected and conversation created, or reply
-forwarded).
+Entries are added when a message is either skipped (not human, already handled,
+or an untriggered reply in a watched thread) or successfully processed (trigger
+detected and conversation created, or triggered reply forwarded).
 
 ---
 
@@ -119,25 +130,33 @@ forwarded).
 
 ```
 [trigger detected]
-        │
-        ▼
+        |
+        v
   status = "active"
   last_activity = now
-        │
-  (next run or later runs)
-        │
-  ┌─────┴──────────────────────────────────────────┐
-  │  User sends a reply in the thread               │
-  │  → send_to_conversation() called               │
-  │  → last_activity = now                         │
-  └─────────────────────────────────────────────────┘
-        │
+  follow-up poll fields initialized
+        |
+        | triggered Slack reply while active
+        | -> send_to_conversation()
+        | -> last_activity = now
+        | -> watch window/backoff reset
+        |
   (when time.time() - last_activity > DONE_DEBOUNCE
-   AND conversation_status ∈ {idle, finished, error, stuck})
-        │
-        ▼
+   AND conversation_status in {idle, finished, error, stuck})
+        |
+        v
   Post summary to Slack thread
+  status = "watching"
+  watch_until = now + THREAD_FOLLOWUP_WATCH_SECONDS
+        |
+        | triggered Slack reply before watch_until
+        | -> send_to_conversation()
+        | -> status = "active"
+        |
+        | no triggered reply before watch_until
+        v
   status = "closed"
+  closed_reason = "followup_watch_expired"
 ```
 
 ---
@@ -158,14 +177,22 @@ forwarded).
       "channel_id": "C0123456789",
       "thread_ts": "1716575900.000100",
       "status": "active",
-      "last_activity": 1716575902.3
+      "last_activity": 1716575902.3,
+      "last_seen_reply_ts": "1716575900.000100",
+      "reply_poll_backoff_seconds": 5,
+      "next_reply_poll_at": 1716575907.3,
+      "watch_until": 1716576202.3
     },
     "C9876543210:1716570000.000500": {
       "conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
       "channel_id": "C9876543210",
       "thread_ts": "1716570000.000500",
-      "status": "closed",
-      "last_activity": 1716572100.0
+      "status": "watching",
+      "last_activity": 1716572100.0,
+      "last_seen_reply_ts": "1716572050.000100",
+      "reply_poll_backoff_seconds": 20,
+      "next_reply_poll_at": 1716572120.0,
+      "watch_until": 1716572400.0
     }
   },
   "bot_message_ts": [