Notification Service
Relevant source files
The following files were used as context for generating this wiki page:
The Notification Service manages the communication between AI agents, the GitHub platform, and human reviewers. It ensures that implementation plans are posted for approval, pull requests are documented, and run failures are reported back to the relevant issue threads.
This system operates as part of the broader "loop" where agents turn tickets into tested pull requests. It utilizes effect handlers to execute external side effects like posting comments or opening pull requests after specific run events occur.
Sources: apps/server/src/worker/effects.service.ts:33, AGENTS.md:6, README.md:12
Architecture and Data Flow
The notification logic resides primarily within the EffectsService in the server application. This service listens for stored effects generated by the run decider and performs asynchronous actions.
The diagram shows how internal run events trigger the EffectsService to communicate with external platforms like GitHub.
Key Notification Triggers
The service responds to specific effect types to update stakeholders on the progress of a run:
| Effect Type | Triggering Condition | Notification Action |
|---|---|---|
post_comment (plan) | Run state is awaiting_approval | Posts the agent's plan to the GitHub issue for human review. |
post_comment (failed) | Run state enters a failed state | Reports the failure reason and provides a link to the web dashboard. |
publish | Implementation and checks are successful | Opens a GitHub Pull Request with the implementation summary and metadata. |
Sources: apps/server/src/worker/effects.service.ts:51-61, apps/server/src/worker/effects.service.ts:101-120
GitHub Integration Logic
The service formats messages based on the current context of the repository and the specific task being performed.
Issue Commenting
When an agent proposes a plan, the post_comment method constructs a Markdown message. This message includes the plan text and a direct link to the Opificia web interface where a human can approve the work.
body = [
"Opificia proposes this plan for the issue.",
"",
run.plan,
"",
"---",
"",
`Approve the plan or ask for changes in Opificia: ${this.webUrl(run.id)}`,
].join("\n");
Sources: apps/server/src/worker/effects.service.ts:104-112
Pull Request Generation
The publish method handles the final notification step. It constructs the Pull Request body using:
- A reference to the original issue (e.g.,
Closes #123). - The implementation summary generated by the agent.
- The original approved plan (collapsed in a
<details>block). - Metadata about the run, including model costs and the result of hygiene checks.
Sources: apps/server/src/worker/effects.service.ts:178-198
Human-in-the-Loop Feedback
The system facilitates a feedback loop through specific events rendered in the web interface and posted back to GitHub.
This sequence illustrates the communication path between the automated agent and the human reviewer via the notification system.
Plan and Feedback Handling
- Plan Proposed: The agent generates a plan via
planPrompt, which is then posted viaEffectsService. - Changes Requested: If a human asks for changes, a
plan.changes_requestedevent is recorded. The web app renders this as aHumanMessageto show the reviewer's feedback. - Sign-off: Humans can sign off on work in a terminal or by using a
/signoffcommand in a GitHub review, which triggers automated commit signing.
Sources: apps/web/src/run/conversation.tsx:288-292, plugins/harness-claude/src/prompts.ts:104-124, CONTRIBUTING.md:105-115
Notification Formatting and Sanitization
To ensure professional and accurate communication, the service and harnesses sanitize outputs before they are sent.
- Attribution Removal: The
withoutAttributionfunction removes habitual model phrases like "Generated with Claude Code" to keep the focus on the actual changes. - Title Splitting: The system parses agent replies to separate the commit title (following Conventional Commits) from the Markdown description for the Pull Request.
- Conventional Commits: Notifications for pull request titles are strictly validated to use standard types like
feat,fix, ordocs.
Sources: plugins/harness-claude/src/prompts.ts:32-41, plugins/harness-claude/src/prompts.ts:77-88, CONTRIBUTING.md:158-166
Summary
The Notification Service ensures transparency throughout the agentic workflow by keeping GitHub issues updated with plans and failure reports. By integrating side effects into the event-sourced run lifecycle, it maintains a clear record of communication between the AI agents and human collaborators, supporting the project's goal of human-centric automation.