Self-Healing Agent Loop

Overview

The platform runs a guarded self-healing loop that uses GitHub Copilot to investigate and fix reported issues automatically.

The loop connects three systems: the built-in error reporter, the client debug reporter, and GitHub Actions workflows that assign Copilot cloud agent to incoming issues.

How It Works

The loop follows these steps:

1. A server or client reporter creates a GitHub issue with auto-reported label.
2. copilot-autofix.yml watches new auto-reported issues and assigns Copilot cloud agent.
3. create-issue-on-failure.yml creates or updates ci-failure issues when CI or Audit Loop fails, and assigns Copilot only on first occurrence.
4. The agent investigates and opens a PR if a safe fix is clear.
5. CI and audit workflows run on the PR.
6. In testing mode, auto-merge-agent-prs.yml can merge safe agent PRs after required checks pass.
7. close-agent-issue-on-merge.yml closes the linked issue when the PR is merged.

What Is Already Wired

Server Error Reporter (utils/error-reporter.js)

• Creates GitHub issues for server crashes and repeated 500-level route errors.
• Adds auto-reported and server-error labels.
• Builds an agent-ready issue body with root-cause and validation instructions.

Client Debug Reporter (routes/debug.js)

• Creates client-reported issues from the pinned debug icon in the admin and client portal shells.
• Adds auto-reported, client-reported, and client-debug labels.
• Includes the note, last action, recent browser events, console logs, viewport, page URL, and screenshot.

GitHub Actions Workflows

Required GitHub Setup

Enable these in your repository:

1. Settings → Actions → General: Actions enabled.
2. Settings → Copilot → Cloud agent: Enable Copilot cloud agent for the repository.
3. Settings → Issues: Issues enabled.
4. Settings → Secrets and variables → Actions: Add COPILOT_AGENT_TOKEN.

COPILOT_AGENT_TOKEN should be a GitHub user token (not a workflow token) with these permissions:

• Actions: read/write
• Contents: read/write
• Issues: read/write
• Pull requests: read/write
• Metadata: read

Environment Variables

On the API service:

GITHUB_ISSUE_TOKEN=github_pat_with_issues_read_write
CLIENT_DEBUG_REPORTER_ENABLED=true
CLIENT_DEBUG_PUBLIC_API_URL=https://api.v2.affinitydesign.ca
CLIENT_DEBUG_SCREENSHOT_TTL_DAYS=90

On the web service:

NEXT_PUBLIC_CLIENT_DEBUG_TOOL=true

Labels

The reporters and workflows try to create labels automatically. If GitHub rejects label creation, create these manually at https://github.com/Affinity-Design/af-gemini-connect/labels:

• bug
• auto-reported
• client-reported
• client-debug
• server-error
• ci-failure

Reviewing Agent PRs

1. Open the PR linked from the issue or the Agents tab.
2. Review the files changed and the PR notes.
3. Check that CI passes or read the failed job output before merging.
4. Confirm the PR body contains a closing keyword linked to the source issue.
5. Mark the PR ready for review if it is still a draft and the patch looks acceptable.
6. Merge manually or let the testing auto-merge workflow merge it.

Manual Recovery

If an issue is created but Copilot is not assigned:

1. Open the issue.
2. In the right sidebar, select Assignees.
3. Select Copilot.
4. Keep the base branch as main and submit.

If Copilot does not appear as an assignee option, check:

• Copilot cloud agent is enabled for the repository.
• The organization policy allows the agent.
• Your account or organization has a supported Copilot plan.
• COPILOT_AGENT_TOKEN has the permissions listed above.