sneak/clawpub
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Compare commits

base: sneak:main
Branches Tags
sneak:main
sneak:update-poller-and-statemachine-docs
sneak:update-poller-docs
sneak:fix/update-poller-docs
sneak:fix/pii-and-conditional-email
sneak:add-notification-delivery-approaches
sneak:rewrite-setup-checklist-prompts
..
compare: sneak:fix/pii-and-conditional-email
Branches Tags
sneak:update-poller-and-statemachine-docs
sneak:main
sneak:update-poller-docs
sneak:fix/update-poller-docs
sneak:fix/pii-and-conditional-email
sneak:add-notification-delivery-approaches
sneak:rewrite-setup-checklist-prompts

No commits in common. "main" and "fix/pii-and-conditional-email" have entirely different histories.
main ... fix/pii-an

1 changed files with 65 additions and 179 deletions
Show Stats Expand all files Collapse all files

244
OPENCLAW_TRICKS.md
View File

@ -189,68 +189,50 @@ arrive instantly.
Setup: add a webhook on each Gitea repo (or use an organization-level webhook) Setup: add a webhook on each Gitea repo (or use an organization-level webhook)
pointing to `https://your-openclaw-host/hooks/gitea`. OpenClaw handles the rest. pointing to `https://your-openclaw-host/hooks/gitea`. OpenClaw handles the rest.
#### Option B: Notification Poller + Dispatcher (Local Machine Behind NAT) #### Option B: Notification Poller (Local Machine Behind NAT)
If your OpenClaw runs on a dedicated local machine behind NAT (like a home Mac If your OpenClaw runs on a dedicated local machine behind NAT (like a home Mac
or Linux workstation), Gitea can't reach it directly. This is our setup — or Linux workstation), Gitea can't reach it directly. This is our setup —
OpenClaw runs on a Mac Studio on a home LAN. OpenClaw runs on a Mac Studio on a home LAN.
The solution: a Python script that both polls and dispatches. It polls the Gitea The solution: a lightweight Python script that polls the Gitea notifications API
notifications API every 15 seconds, triages each notification (checking every few seconds. When new notifications appear, it writes a flag file that the
assignment and @-mentions), marks them as read, and spawns one isolated agent agent checks during heartbeats.
session per actionable item via `openclaw cron add --session isolated`.
The poller also runs a secondary **assignment scan** every 2 minutes, checking
all watched repos for open issues/PRs assigned to the bot that were recently
updated and still need a response. This catches cases where notifications aren't
generated (e.g. self-assignment, API-created issues).
Key design decisions: Key design decisions:
- **The poller IS the dispatcher.** No flag files, no heartbeat dependency. The - **The poller never marks notifications as read.** The agent does that after
poller triages notifications and spawns agents directly. processing. This prevents lost notifications if the agent fails to process.
- **Marks notifications as read immediately.** Each notification is marked read - **It tracks notification IDs, not counts.** Only fires on genuinely new
as it's processed, preventing re-dispatch on the next poll. notifications, not re-reads of existing ones.
- **One agent per issue.** Each spawned agent gets a `SCOPE` instruction - **Flag file instead of wake events.** We initially used OpenClaw's
limiting it to one specific issue/PR. Agents post results as Gitea comments, `/hooks/wake` endpoint, but wake events target the main (DM) session — any
not DMs. model response during processing leaked to DM as a notification. The flag file
- **Dedup tracking.** An in-memory `dispatched_issues` set prevents spawning approach is processed during heartbeats, where output routing is controlled.
multiple agents for the same issue within one poller lifetime.
- **`--no-deliver` instead of `--announce`.** Agents report via Gitea API
directly. The `--announce` flag on isolated sessions had delivery failures.
- **Assignment scan filters by recency.** Only issues updated in the last 5
minutes are considered, preventing re-dispatch for stale assigned issues.
- **Zero dependencies.** Just Python stdlib. Runs anywhere. - **Zero dependencies.** Just Python stdlib. Runs anywhere.
Response time: ~15–60s from notification to agent comment (vs ~30 min with the Tradeoff: notifications are processed at heartbeat cadence (~30 min) instead of
old heartbeat approach). realtime. For code review and issue triage, this is fine.
```python ```python
#!/usr/bin/env python3 #!/usr/bin/env python3
""" """
Gitea notification poller + dispatcher. Gitea notification poller (flag-file approach).
Polls for unread notifications and writes a flag file when new ones
Two polling loops: appear. The agent checks this flag during heartbeats and processes
1. Notification-based: detects new notifications (mentions, assignments by notifications via the Gitea API directly.
other users) and dispatches agents for actionable ones.
2. Assignment-based: periodically checks for open issues/PRs assigned to
the bot that have no recent bot comment. Catches cases where
notifications aren't generated (e.g. self-assignment, API-created issues).
Required env vars: Required env vars:
GITEA_URL - Gitea instance URL GITEA_URL - Gitea instance URL
GITEA_TOKEN - Gitea API token GITEA_TOKEN - Gitea API token
Optional env vars: Optional env vars:
POLL_DELAY - Delay between polls in seconds (default: 15) FLAG_PATH - Path to flag file (default: workspace/memory/gitea-notify-flag)
COOLDOWN - Minimum seconds between dispatches (default: 30) POLL_DELAY - Delay between polls in seconds (default: 5)
ASSIGNMENT_INTERVAL - Seconds between assignment scans (default: 120)
OPENCLAW_BIN - Path to openclaw binary
""" """
import json import json
import os import os
import subprocess
import sys import sys
import time import time
import urllib.request import urllib.request
@ -258,158 +240,62 @@ import urllib.error
GITEA_URL = os.environ.get("GITEA_URL", "").rstrip("/") GITEA_URL = os.environ.get("GITEA_URL", "").rstrip("/")
GITEA_TOKEN = os.environ.get("GITEA_TOKEN", "") GITEA_TOKEN = os.environ.get("GITEA_TOKEN", "")
POLL_DELAY = int(os.environ.get("POLL_DELAY", "15")) POLL_DELAY = int(os.environ.get("POLL_DELAY", "5"))
COOLDOWN = int(os.environ.get("COOLDOWN", "30")) FLAG_PATH = os.environ.get(
ASSIGNMENT_INTERVAL = int(os.environ.get("ASSIGNMENT_INTERVAL", "120")) "FLAG_PATH",
OPENCLAW_BIN = os.environ.get("OPENCLAW_BIN", "/opt/homebrew/bin/openclaw") os.path.join(
BOT_USER = "clawbot" # Change to your bot's Gitea username os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
"memory",
# Repos to scan for assigned issues "gitea-notify-flag",
WATCHED_REPOS = [ ),
# "org/repo1", )
# "org/repo2",
]
# Track dispatched issues to prevent duplicates
dispatched_issues = set()
def gitea_api(method, path, data=None): def check_config():
url = f"{GITEA_URL}/api/v1{path}" if not GITEA_URL or not GITEA_TOKEN:
body = json.dumps(data).encode() if data else None print("ERROR: GITEA_URL and GITEA_TOKEN required", file=sys.stderr)
headers = {"Authorization": f"token {GITEA_TOKEN}"} sys.exit(1)
if body:
headers["Content-Type"] = "application/json"
req = urllib.request.Request(url, headers=headers, method=method, data=body)
try:
with urllib.request.urlopen(req, timeout=15) as resp:
raw = resp.read()
return json.loads(raw) if raw else None
except Exception as e:
print(f"WARN: {method} {path}: {e}", file=sys.stderr, flush=True)
return None
def needs_bot_response(repo_full, issue_number): def gitea_unread_ids():
"""True if the bot is NOT the author of the most recent comment.""" req = urllib.request.Request(
comments = gitea_api("GET", f"/repos/{repo_full}/issues/{issue_number}/comments") f"{GITEA_URL}/api/v1/notifications?status-types=unread",
if comments and len(comments) > 0: headers={"Authorization": f"token {GITEA_TOKEN}"},
if comments[-1].get("user", {}).get("login") == BOT_USER:
return False
return True
def is_actionable(notif):
"""Returns (actionable, reason, issue_number)."""
subject = notif.get("subject", {})
repo = notif.get("repository", {})
repo_full = repo.get("full_name", "")
url = subject.get("url", "")
number = url.rstrip("/").split("/")[-1] if url else ""
if not number or not number.isdigit():
return False, "no issue number", None
issue = gitea_api("GET", f"/repos/{repo_full}/issues/{number}")
if not issue:
return False, "couldn't fetch issue", number
assignees = [a.get("login") for a in (issue.get("assignees") or [])]
if BOT_USER in assignees:
if needs_bot_response(repo_full, number):
return True, f"assigned to {BOT_USER}", number
return False, "assigned but already responded", number
issue_body = issue.get("body", "") or ""
if f"@{BOT_USER}" in issue_body and issue.get("user", {}).get("login") != BOT_USER:
if needs_bot_response(repo_full, number):
return True, f"@-mentioned in body", number
comments = gitea_api("GET", f"/repos/{repo_full}/issues/{number}/comments")
if comments:
last = comments[-1]
if last.get("user", {}).get("login") == BOT_USER:
return False, "own comment is latest", number
if f"@{BOT_USER}" in (last.get("body") or ""):
return True, f"@-mentioned in comment", number
return False, "not mentioned or assigned", number
def spawn_agent(repo_full, issue_number, title, subject_type, reason):
dispatch_key = f"{repo_full}#{issue_number}"
if dispatch_key in dispatched_issues:
return
dispatched_issues.add(dispatch_key)
repo_short = repo_full.split("/")[-1]
job_name = f"gitea-{repo_short}-{issue_number}-{int(time.time())}"
msg = (
f"Gitea: {reason} on {subject_type} #{issue_number} "
f"'{title}' in {repo_full}.\n"
f"API: {GITEA_URL}/api/v1 | Token: {GITEA_TOKEN}\n"
f"SCOPE: Only {subject_type} #{issue_number} in {repo_full}.\n"
f"Read all comments, do the work, post results as Gitea comments."
) )
try: try:
subprocess.run( with urllib.request.urlopen(req, timeout=10) as resp:
[OPENCLAW_BIN, "cron", "add", return {n["id"] for n in json.loads(resp.read())}
"--name", job_name, "--at", "1s",
"--message", msg, "--delete-after-run",
"--session", "isolated", "--no-deliver",
"--thinking", "low", "--timeout-seconds", "300"],
capture_output=True, text=True, timeout=15,
)
except Exception as e: except Exception as e:
print(f"Spawn error: {e}", file=sys.stderr, flush=True) print(f"WARN: Gitea API failed: {e}", file=sys.stderr, flush=True)
dispatched_issues.discard(dispatch_key) return set()
def write_flag(count):
os.makedirs(os.path.dirname(FLAG_PATH), exist_ok=True)
with open(FLAG_PATH, "w") as f:
f.write(json.dumps({
"ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
"count": count,
}))
def main(): def main():
print(f"Poller started (poll={POLL_DELAY}s, cooldown={COOLDOWN}s)", flush=True) check_config()
seen_ids = set(n["id"] for n in (gitea_api("GET", "/notifications?status-types=unread") or [])) print(f"Gitea poller started (delay={POLL_DELAY}s, flag={FLAG_PATH})", flush=True)
last_dispatch = 0 last_seen_ids = gitea_unread_ids()
last_assign_scan = 0 print(f"Initial unread: {len(last_seen_ids)}", flush=True)
while True: while True:
time.sleep(POLL_DELAY) time.sleep(POLL_DELAY)
now = time.time() current_ids = gitea_unread_ids()
new_ids = current_ids - last_seen_ids
# Notification polling if not new_ids:
notifs = gitea_api("GET", "/notifications?status-types=unread") or [] last_seen_ids = current_ids
current_ids = {n["id"] for n in notifs} continue
new_ids = current_ids - seen_ids ts = time.strftime("%H:%M:%S")
if new_ids and now - last_dispatch >= COOLDOWN: print(f"[{ts}] {len(new_ids)} new ({len(current_ids)} total), flag written", flush=True)
for n in [n for n in notifs if n["id"] in new_ids]: write_flag(len(new_ids))
nid = n.get("id") last_seen_ids = current_ids
if nid:
gitea_api("PATCH", f"/notifications/threads/{nid}")
is_act, reason, num = is_actionable(n)
if is_act:
repo = n["repository"]["full_name"]
title = n["subject"]["title"][:60]
stype = n["subject"].get("type", "").lower()
spawn_agent(repo, num, title, stype, reason)
last_dispatch = now
seen_ids = current_ids
# Assignment scan (less frequent)
if now - last_assign_scan >= ASSIGNMENT_INTERVAL:
for repo in WATCHED_REPOS:
for itype in ["issues", "pulls"]:
items = gitea_api("GET",
f"/repos/{repo}/issues?state=open&type={itype}"
f"&assignee={BOT_USER}&sort=updated&limit=10") or []
for item in items:
num = str(item["number"])
if f"{repo}#{num}" in dispatched_issues:
continue
# Only recently updated items (5 min)
# ... add is_recently_updated() check here
if needs_bot_response(repo, num):
spawn_agent(repo, num, item["title"][:60],
"pull" if itype == "pulls" else "issue",
f"assigned to {BOT_USER}")
last_assign_scan = now
if __name__ == "__main__": if __name__ == "__main__":