Make setupOpenClawOrchestrator own GitHub mention hooks idempotently

[OpenCodeEngineer]

Summary

Extend setupOpenClawOrchestrator.ts so reruns always provision and preserve OpenClaw GitHub mention orchestration (@githubap, @ClawEngineer) in an idempotent way.

Required behavior

• Add dedicated configureGithubMentionHooks(...) setup step after gateway/model config.
• Ensure config keys are set each run:
  • hooks.enabled=true
  • hooks.token=${OPENCLAW_HOOKS_TOKEN} (generate once if missing and persist in ~/.openclaw/.env)
  • hooks.allowRequestSessionKey=true
  • hooks.allowedSessionKeyPrefixes=["hook:github:"]
  • hooks.transformsDir="~/.openclaw/hooks/transforms"
• Upsert mapping hooks.mappings["github-mentions"]:
  • action agent, agentId=main
  • transform.module="github-mentions.ts"
  • match for issue_comment, pull_request_review_comment, discussion_comment plus optional pull_request_review submitted body via transform.
• Materialize transform file ~/.openclaw/hooks/transforms/github-mentions.ts with:
  • mention filter for @githubap and @ClawEngineer (CLI override supported)
  • loop prevention for bot/self authors
  • deterministic session key format: hook:github:<owner>/<repo>:<kind>:<id>
  • structured agent payload message
  • HMAC verification with GITHUB_APP_WEBHOOK_SECRET
• Print final webhook metadata in JSON output:
  • webhookPath, hooksEnabled, mentionsHandles, transformPath

CLI/options

• Add repeatable: --github-mention-handle <@handle>
• Add opt-out: --disable-github-mention-hooks
• Add explicit rotation flag: --rotate-hooks-token

Idempotency

• Never rotate existing OPENCLAW_HOOKS_TOKEN unless --rotate-hooks-token is provided.
• Never rewrite transform when content hash is unchanged.
• Preserve existing custom mappings; only upsert/remove github-mentions entry.
• Hard fail if mention hooks are enabled but GITHUB_APP_WEBHOOK_SECRET is missing.

Validation

• Fresh run creates hooks config + transform + token.
• Re-run does not duplicate mapping or churn token.
• Mention payload accepted only with valid signature and matching handle.
• Non-mention/bot payload ignored.
• Config smoke verifies hooks settings and mapping target.

[OpenCodeEngineer]

Implemented and validated in /Users/engineer/workspace/setupOpenClawOrchestrator.ts.

Status:

• Added dedicated configureGithubMentionHooks(...) step in main flow after model/gateway config.
• Added CLI flags:
  • --github-mention-handle (repeatable)
  • --disable-github-mention-hooks
  • --rotate-hooks-token
• Enforced and persisted hook config every run:
  • hooks.enabled=true
  • hooks.token=${OPENCLAW_HOOKS_TOKEN}
  • hooks.allowRequestSessionKey=true
  • hooks.allowedSessionKeyPrefixes=["hook:github:"]
  • hooks.transformsDir="~/.openclaw/hooks/transforms"
• Implemented mapping upsert for github-mentions while preserving custom mappings.
• Implemented transform materialization at ~/.openclaw/hooks/transforms/github-mentions.ts with:
  • mention filtering for configured handles
  • bot/self loop prevention
  • deterministic session keys hook:github:<owner>/<repo>:<kind>:<id>
  • structured agent message payload
  • HMAC verification via GITHUB_APP_WEBHOOK_SECRET
• Added final JSON output fields:
  • webhookPath, hooksEnabled, mentionsHandles, transformPath
• Enforced hard-fail when mention hooks are enabled and GITHUB_APP_WEBHOOK_SECRET is missing.

Validation performed:

• Fresh run path creates hooks config + transform + token.
• Re-run is idempotent (no duplicate mapping, no token churn, unchanged transform hash).
• Rotation only occurs with --rotate-hooks-token.
• Valid signed mention payload accepted.
• Invalid signature/non-mention/bot-author payloads ignored.
• Config smoke values match required hooks settings.

[OpenCodeEngineer]

Update: simplified implementation has been applied per latest direction (minimal flow, no extra feature flags).

What changed now:

• Removed mention-hook feature flags/options from CLI:
  • no --github-mention-handle
  • no --disable-github-mention-hooks
  • no --rotate-hooks-token
• Kept one fixed ingress mapping only:
  • id: "github"
  • match.path: "github"
  • action: "agent"
  • agentId: "main"
  • transform.module: "github-mentions.ts"
• Setup always enforces hook config and fails fast if GITHUB_APP_WEBHOOK_SECRET is missing.
• OPENCLAW_HOOKS_TOKEN is create-if-missing and stable across reruns.
• Output now reports minimal webhook setup status:
  • webhookPath, hooksEnabled, transformPath

Transform behavior now targets requested loop:

• Accepts signed GitHub webhook events.
• Starts on:
  • issues.assigned to app login githubapp
  • app mention in issue/PR/discussion events.
• Continues issue thread on user comments when the issue is assigned to app (no mention required).
• Ignores bot/self events for loop prevention.
• Uses deterministic thread session keys: hook:github:<owner>/<repo>:<kind>:<threadId>.

Validation run completed:

• dry-run success + missing-secret hard-fail
• non-dry-run fake OpenClaw harness: token stable, mapping stable, transform hash stable
• fixed mapping reset behavior verified
• transform fixtures verified for assigned trigger, mention trigger, follow-up issue comment, invalid signature ignore, bot ignore, PR review comment mention, discussion mention, PR review submitted mention

[OpenCodeEngineer]

Applied follow-up fix: app handle is no longer hardcoded to example values.

Now the setup resolves real app identity in this order:

1. OPENCLAW_GITHUB_APP_LOGIN / GITHUB_APP_LOGIN env override (explicit)
2. GitHub API /app slug using GitHub App credentials (non-dry-run)

The generated transform uses resolved logins/handles and accepts assignment for both <app> and <app>[bot], plus mentions for @<app> and @<app>[bot].

Also tightened transform file permissions to 0600 when materialized under ~/.openclaw/hooks/transforms/github-mentions.ts.

[OpenCodeEngineer]

Status update (implemented + validated):

1. Script fix applied

• Updated /Users/engineer/workspace/setupOpenClawOrchestrator.ts to set:
  • hooks.allowedSessionKeyPrefixes = ["hook:", "hook:github:"]
• This fixes current OpenClaw runtime validation (hooks.allowedSessionKeyPrefixes must include 'hook:' when defaultSessionKey is unset).

2. Real GitHub App created and wired

• App: ClawEngineer (@clawengineer)
• App ID: 3009676
• Client ID: Iv23liIsvv3zOkr5HXYg
• Private key: ~/.openclaw/github-app/clawengineer.private-key.pem
• Webhook secret configured and enforced.

3. Setup rerun succeeded end-to-end

• bun /Users/engineer/workspace/setupOpenClawOrchestrator.ts ... now completes successfully.
• Health checks pass (openclaw gateway health --json => ok: true).
• Final JSON includes:
  • webhookPath: /hooks/github
  • hooksEnabled: true
  • transformPath: ~/.openclaw/hooks/transforms/github-mentions.ts
  • githubAppLogin: clawengineer
  • mentionHandles: ["@clawengineer", "@clawengineer[bot]"]

4. Validation run results

• Config smoke:
  • hooks.enabled = true
  • mapping exists: id=github, path=github, transform.module=github-mentions.ts
• Transform behavior (direct hook tests with valid token):
  • mention payload => 200 + {"ok":true,"runId":...}
  • non-mention payload => 204
  • bot-authored payload => 204
  • invalid signature => 204
• Live GitHub webhook delivery test:
  • Created issue: dzianisv/AiDocumentsOrganizer#6
  • Posted mention comment to @clawengineer
  • GitHub delivery recorded (issue_comment.created) with status_code=200
  • Delivery payload confirmed repository + mention content.
  • OpenClaw session key created for that thread:
    • agent:main:hook:github:dzianisv/aidocumentsorganizer:issue:6

5. Observed operational caveat from live test

• Assignment-to-app on tested repo returned empty assignees (assignees: []) because the app bot user was not assignable in that repo context.
• Mention trigger path is functioning and reaches OpenClaw correctly.

[OpenCodeEngineer]

Additional update:

• Added one more hardening fix in setupOpenClawOrchestrator.ts so reruns also persist resolved app identity keys in runtime env:

  • GITHUB_APP_LOGIN
  • OPENCLAW_GITHUB_APP_LOGIN
  • GITHUB_APP_SLUG

• This prevents stale handle drift from older app configs and keeps mention handle resolution aligned with the real app (clawengineer).

• Added local helper launcher for live testing:

  • /Users/engineer/workspace/start-clawengineer-webhook-bridge.sh
  • It starts local webhook relay + cloudflared tunnel and patches GitHub App webhook URL automatically for the current run.

Validation after this patch:

• setup rerun succeeds
• .env now has GITHUB_APP_SLUG=clawengineer, GITHUB_APP_LOGIN=clawengineer, OPENCLAW_GITHUB_APP_LOGIN=clawengineer
• hook tests still pass (mention=200 with runId, non-mention/bot/bad-signature=204).

[OpenCodeEngineer]

Status update (2026-03-04):

• Re-ran /Users/engineer/workspace/setupOpenClawOrchestrator.ts with real GitHub App identity clawengineer and verified idempotency.
• OPENCLAW_HOOKS_TOKEN is stable across reruns (no churn).
• Hook mapping remains single/upserted entry: id=github, path=github, transform github-mentions.ts.
• Transform file remained unchanged on rerun (content hash stable).
• Config smoke checks pass:
  • hooks.enabled=true
  • hooks.allowedSessionKeyPrefixes=["hook:","hook:github:"]
  • hooks.transformsDir=~/.openclaw/hooks/transforms
• Ingress behavior validated locally with signed payloads:
  • mention -> 200 and agent run created
  • non-mention -> 204 ignored
  • bot author -> 204 ignored
  • bad signature -> 204 ignored
• Deterministic session key confirmed in state: agent:main:hook:github:dzianisv/aidocumentsorganizer:issue:6.

Current ready-to-test setup:

• App handle: @clawengineer (also @clawengineer[bot])
• Hook endpoint path: /hooks/github
• Bridge helper script: /Users/engineer/workspace/start-clawengineer-webhook-bridge.sh (for GitHub -> local hook delivery).

[OpenCodeEngineer]

Final implementation update (2026-03-04):

Implemented additional GitHub-delivery wiring so hook-triggered agent output is posted back into the same GitHub thread as the ClawEngineer app.

What changed in /Users/engineer/workspace/setupOpenClawOrchestrator.ts:

• Hook transform now sets outbound routing for issue/PR events:
  • deliver: true
  • channel: "github"
  • to: "<owner>/<repo>#<number>"
• Hook setup now also ensures GitHub channel delivery basics:
  • channels.github.enabled=true
  • channels.github.botLogin=<resolved app login>
  • channels.github.webhookSecret=${GITHUB_APP_WEBHOOK_SECRET}
• GitHub installation token refresh now also updates:
  • channels.github.token=<fresh installation token>
  • launchctl setenv OPENCLAW_GITHUB_TOKEN <fresh token> (prevents ambient personal GITHUB_TOKEN from being used)
  • launchctl setenv OPENCLAW_GITHUB_WEBHOOK_SECRET <secret>
• Runtime env now persists:
  • OPENCLAW_GITHUB_TOKEN
  • OPENCLAW_GITHUB_WEBHOOK_SECRET

Validation run summary:

• Setup rerun successful, idempotent token/file checks still pass.
• Hooks smoke checks pass (hooks.enabled=true, mapping to github-mentions.ts present).
• Local signed hook mention -> OpenClaw run created and GitHub reply posted by clawengineer[bot].
• Live bridge test (@clawengineer issue comment) -> OpenClaw ingested and replied on same issue as clawengineer[bot].

Latest proof thread used:

• dzianisv/AiDocumentsOrganizer#6
• latest bot replies include comment IDs 4000682790 and 4000685488.

[OpenCodeEngineer]

Final verification after token-source fix:

• Added launchctl setenv OPENCLAW_GITHUB_TOKEN <app installation token> and runtime OPENCLAW_GITHUB_TOKEN persistence so GitHub outbound no longer uses ambient personal GITHUB_TOKEN.
• Added OPENCLAW_GITHUB_WEBHOOK_SECRET persistence + launchctl setenv.
• Re-ran setup script and validated channel probe now reports: GitHub App installation token (repositories: 163).

E2E proof:

• Local signed hook mention to /hooks/github created run and posted reply as clawengineer[bot]:
  • reply comment id 4000682790 on dzianisv/AiDocumentsOrganizer#6.
• Live GitHub mention (@clawengineer live-final-e2e-bridge-check-1772663070) delivered via bridge and OpenClaw replied as clawengineer[bot]:
  • reply comment id 4000685488 on same issue.

This confirms the full loop is now operational with the real GitHub App identity.

[OpenCodeEngineer]

Status update (2026-03-04 14:44 PT):

• Added test skill: .agents/skills/github-mention-e2e-playwriter/SKILL.md.
• Bridge refreshed and webhook patched to current tunnel URL:
  • https://generated-tennis-butler-uncertainty.trycloudflare.com/github
• Fresh E2E mention loop validated on dzianisv/AiDocumentsOrganizer#6:
  • User mention comment: OpenClaw E2E 1772660879 AiDocumentsOrganizer#6 (comment)
  • Bot reply comment: OpenClaw E2E 1772660879 AiDocumentsOrganizer#6 (comment)
  • Marker: pw-e2e-17726641893N
• OpenClaw ingest/session evidence:
  • session key: agent:main:hook:github:dzianisv/aidocumentsorganizer:issue:6
  • inbound payload and marker recorded in ~/.openclaw/agents/main/sessions/a2f6c2cc-24b2-4842-b8b7-96c0f3a7633e.jsonl

Note: playwriter and chrome-devtools MCP tool endpoints in this Codex session currently return Transport closed; E2E was completed with the same protocol via CLI/API path while bridge/webhook were live.

[OpenCodeEngineer]

Localhost deployment script hardening + verification complete (2026-03-04 15:02 PT).

Changes made:

• Updated /Users/engineer/workspace/setupOpenClawOrchestrator.ts to include strict localhost readiness validation after setup.
• Added readiness result to final JSON output under localhostReadiness.
• Added reusable skill for this routine:
  • .agents/skills/openclaw-localhost-deploy-verify/SKILL.md

Readiness checks now enforced in script:

• hooks.enabled=true
• hooks.mappings contains github mapping -> github-mentions.ts
• channels.github.configured=true
• channels.github.running=true
• channels.github.webhookPath=/github

Validation executed:

1. Real setup run: bun /Users/engineer/workspace/setupOpenClawOrchestrator.ts -> PASS (includes localhostReadiness all true)
2. Idempotency rerun -> PASS

• OPENCLAW_HOOKS_TOKEN stable
• transform hash unchanged

3. Live mention E2E after patch -> PASS

• user comment: OpenClaw E2E 1772660879 AiDocumentsOrganizer#6 (comment)
• bot reply: OpenClaw E2E 1772660879 AiDocumentsOrganizer#6 (comment)
• marker: localhost-postpatch-e2e-17726650873N
• session evidence: ~/.openclaw/agents/main/sessions/f46a74ae-4e4e-4886-8e67-1463ee7bd174.jsonl

Current gateway remains localhost-only (127.0.0.1:18789).

[OpenCodeEngineer]

Update: standardized bridge tooling to TypeScript in the new dzianisv/CodeClaw repo.

Delivered:

• Replaced shell bridge with TS bridge script:
  • scripts/start-clawengineer-webhook-bridge.ts
• Removed shell version:
  • scripts/start-clawengineer-webhook-bridge.sh
• Updated README + skill defaults to use TS bridge.
• Added valid YAML frontmatter to both local skill files in CodeBridge and CodeClaw so skill loaders stop skipping them.

Validation:

• Ran bun scripts/start-clawengineer-webhook-bridge.ts successfully; it started relay, created Cloudflare tunnel, patched GitHub webhook, and printed Bridge ready.
• Clean shutdown via Ctrl+C verified.
• Verified CodeBridge skill files now parse frontmatter successfully.

CodeClaw commits:

• f5aaada Switch webhook bridge to TypeScript and fix skill frontmatter
• fff4335 Harden TypeScript bridge startup and port cleanup
• 7deb4a1 Improve bridge process startup robustness

[OpenCodeEngineer]

Status update (2026-03-04 PST): End-to-end GitHub mention flow is now working with real app identity @clawengineer.

What was executed live:

• Re-ran setup: bun /Users/engineer/workspace/CodeClaw/scripts/setupOpenClawOrchestrator.ts
• Started TS bridge: bun /Users/engineer/workspace/CodeClaw/scripts/start-clawengineer-webhook-bridge.ts
• Triggered real issue-comment mentions on dzianisv/AiDocumentsOrganizer#6

Evidence (comment URLs):

1. Trigger: OpenClaw E2E 1772660879 AiDocumentsOrganizer#6 (comment)
   Bot reply: OpenClaw E2E 1772660879 AiDocumentsOrganizer#6 (comment)
2. Follow-up trigger: OpenClaw E2E 1772660879 AiDocumentsOrganizer#6 (comment)
   Bot reply: OpenClaw E2E 1772660879 AiDocumentsOrganizer#6 (comment)
3. Follow-up trigger (repo-scoped task): OpenClaw E2E 1772660879 AiDocumentsOrganizer#6 (comment)
   Bot reply: OpenClaw E2E 1772660879 AiDocumentsOrganizer#6 (comment)

Observed behavior:

• Mention ingestion works.
• OpenClaw executes task and replies back in-thread as clawengineer.
• Follow-up comments are received and answered.
• Cross-repo request in a repo-scoped issue was correctly rejected by guardrails; repo-scoped follow-up task succeeded.

Repo update pushed:

• dzianisv/CodeClaw@9b12785
• Commit: "Harden GitHub hook automation policy for localhost E2E"

[OpenCodeEngineer]

Final update after review hardening:

• Pushed follow-up commit: ac07fad (Constrain hook automation wording to repo-scoped actions).
• Re-ran localhost setup and live verification.
• Additional E2E proof:
  • Trigger: OpenClaw E2E 1772660879 AiDocumentsOrganizer#6 (comment)
  • Bot reply: OpenClaw E2E 1772660879 AiDocumentsOrganizer#6 (comment)

Current status: mention ingress, task execution, and in-thread GitHub replies are working with @clawengineer.

[OpenCodeEngineer]

Rerun test report (2026-03-04 PST)\n\nMatrix executed:\n- T1 issue assigned to app handle (real GitHub assignment)\n- T2 issue comment mention\n- T3 discussion comment mention\n- T4a PR conversation comment mention\n- T4b PR review submitted-body mention\n\nResults:\n- T1 real assignment: BLOCKED by GitHub\n - gh issue edit ... --add-assignee clawengineer -> failed ... 'clawengineer' not found\n - gh issue edit ... --add-assignee clawengineer[bot] -> same error\n - Fallback validation (signed synthetic issues.assigned webhook to /hooks/github) passed:\n - marker rr-assign-synth-1772683080\n - bot reply: https://github.com/dzianisv/AiDocumentsOrganizer/issues/6#issuecomment-4001965737\n- T2 issue mention: PASS\n - trigger: https://github.com/dzianisv/AiDocumentsOrganizer/issues/6#issuecomment-4001947974\n - bot reply: https://github.com/dzianisv/AiDocumentsOrganizer/issues/6#issuecomment-4001948415\n- T3 discussion mention ingestion: PASS (ingress) / NO thread reply by design\n - created discussion target: https://github.com/dzianisv/openhaystack-web/discussions/2\n - trigger: https://github.com/dzianisv/openhaystack-web/discussions/2#discussioncomment-16004909\n - OpenClaw session captured event=discussion_comment, kind=discussion, marker rr-disc-1772682848\n- T4a PR conversation mention: PASS\n - trigger: https://github.com/dzianisv/AiDocumentsOrganizer/pull/4#issuecomment-4001960127\n - bot reply: https://github.com/dzianisv/AiDocumentsOrganizer/pull/4#issuecomment-4001960585\n- T4b PR review mention: PASS\n - review marker rr-prr-1772683025 submitted on PR #4\n - bot reply: https://github.com/dzianisv/AiDocumentsOrganizer/pull/4#issuecomment-4001962112\n\nInfra used during rerun:\n- setup script (already applied), gateway healthy\n- bridge restarted and active during tests\n- webhook tunnel: https://tan-fine-area-heading.trycloudflare.com/github (ephemeral)\n\nIf needed, I can now patch discussion delivery so discussion mentions also post back to discussion threads (currently transform uses deliver=false for kind=discussion).

[OpenCodeEngineer]

Update: executed fresh localhost setup + TypeScript E2E matrix and generated a new codebridge-test report.

Report artifact:

• /Users/engineer/workspace/CodeClaw/reports/codebridge-test-report-2026-03-05T04-40-49-582Z.md

Run summary (2026-03-05 04:37Z - 04:40Z):

• App: ClawEngineer (@clawengineer)
• Bridge webhook URL: https://creative-pipes-performance-files.trycloudflare.com/github
• Installation state: app installed for dzianisv only, not installed for org VibeTechnologies

Test outcomes:

1. issue-assigned (org codebridge-test): FAIL
   • https://github.com/VibeTechnologies/codebridge-test/issues/1
2. issue-comment-mention (dzianisv issue): PASS
   • trigger: https://github.com/dzianisv/AiDocumentsOrganizer/issues/6#issuecomment-4002136660
   • bot reply: https://github.com/dzianisv/AiDocumentsOrganizer/issues/6#issuecomment-4002136908
3. pr-review-mention: PASS
   • trigger: https://github.com/dzianisv/AiDocumentsOrganizer/pull/4#pullrequestreview-3893639273
   • bot reply: https://github.com/dzianisv/AiDocumentsOrganizer/pull/4#issuecomment-4002137247
4. discussion-comment-mention: FAIL (ingress only, no thread reply)
   • trigger: https://github.com/dzianisv/openhaystack-web/discussions/2#discussioncomment-16005187
5. issue-comment-mention (codebridge-org): FAIL (no ingress, no reply)
   • trigger: https://github.com/VibeTechnologies/codebridge-test/issues/1#issuecomment-4002142116

Root blocker for org rollout:

• No VibeTechnologies installation exists for app clawengineer, so org repos cannot deliver events to OpenClaw yet.
• Org install URL (All repositories): https://github.com/apps/clawengineer/installations/new?target_id=222073366

Code changes in dzianisv/CodeClaw:

• Added runner: scripts/runGithubMentionE2ETest.ts
• Added skill: .agents/skills/github-mention-e2e-runner/SKILL.md
• Updated README usage and report locations.