What is the Neural Link?

The Neural Link is a bi-directional bridge that connects AI agents directly to the Neo.mjs runtime. It lets agents inspect the Scene Graph, component state, event listeners, computed styles, and DOM rectangles, and mutate the running application in real time.

Why is Neo.mjs called an Application Engine instead of a framework?

Neo.mjs maintains persistent application objects in a worker-backed Scene Graph instead of compiling application state away into ephemeral DOM nodes. That architecture enables multi-window orchestration, runtime permutation, and deep AI introspection.

What is Context Engineering?

Context Engineering shapes the information and tool environment around AI agents. Neo.mjs implements it through Knowledge Base, Memory Core, GitHub Workflow, and Neural Link MCP servers for frontier harnesses, plus a File System MCP server for internal Neo.ai.Agent local loops.

What is the Neo.mjs Agent OS?

The Neo.mjs Agent OS is the repository Brain: source code and services for Memory Core, Knowledge Base, Active Hybrid GraphRAG, DreamService, Golden Path synthesis, A2A coordination, and Neural Link tooling.

Frontmatter

id	12937
title	Add GitHub @mention notifications to the heartbeat (github-repo-gated)
state	Closed
labels	enhancementaiarchitecturemodel-experience
assignees	neo-gpt
createdAt	Jun 12, 2026, 2:56 AM
updatedAt	Jun 13, 2026, 4:28 PM
githubUrl	https://github.com/neomjs/neo/issues/12937
author	neo-opus-grace
commentsCount	3
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	Jun 13, 2026, 4:28 PM

Add GitHub @mention notifications to the heartbeat (github-repo-gated)

Closed v13.1.0/archive-v13-1-0-chunk-1 enhancementaiarchitecturemodel-experience

neo-opus-grace commented on Jun 12, 2026, 2:56 AM

Context

Friction→gold from the 2026-06-11/12 night session (operator-directed). The operator asked whether the "GitHub events reach agents" capability was stale — V-B-A confirmed it is stale in effect. Epic #10214 (closed) → Sub #10218 (closed) built a passive notificationPreview in the github-workflow healthcheck, but it dead-ends: nothing consumes it and the wake/heartbeat path never ingests GitHub mentions, so an agent tagged in a PR/issue/comment never discovers it within the session — exactly #10218's own stated (still-unmet) goal.

The Problem

Agents have GitHub accounts and receive @mention notifications (review requests, comment tags). Today:

ai/services/github-workflow/HealthService.mjs fetches gh api 'notifications?participating=true', filters n.reason === 'mention', and writes payload.notificationPreview (unreadCount + latest 5). LIVE but unconsumed — grep finds zero readers of notificationPreview outside HealthService.
The wake/heartbeat path (SwarmHeartbeatService / wake daemon) ingests only A2A + GraphLog signals — never GitHub notifications.
Net: a GitHub tag lands in GitHub's feed and dies there unless an agent manually runs healthcheck and inspects the field. The inbound-from-the-world signal is built but never delivered.

The Architectural Reality

Source primitive exists: HealthService.mjs (notifications?participating=true → reason === 'mention').
Delivery substrate: the heartbeat/wake path — SwarmHeartbeatService.pulse() (ai/daemons/orchestrator/services/) + the wake daemon. This is where the GitHub-notification signal must be injected to actually reach the agent.
Deployment-conditional constraint (operator, hard requirement): fire only when a GitHub repo is actually in use. Must NOT fire for GitLab-backed, local-only, or non-GitHub deployments. Mirror the deployment-portable resolver precedent from #11829 (resolveSwarmHeartbeatTargets()) + ADR 0014 cloud-deployment topology — github-event ingestion is auto-detected / opt-in per deployment, never hardcoded.

The Fix

Promote the passive preview to an active heartbeat signal, github-repo-gated:

Gate on github-repo usage (auto-detect / config) — no-op (disabled-with-log) for non-GitHub deployments.
On the heartbeat cycle, fetch unread reason=mention (+ likely review_requested) notifications.
Inject them into the heartbeat/wake payload so a tag wakes/reaches the agent — with dedup / read-state so the same notification wakes once, not every heartbeat (mirror the A2A mailbox read-state model).
(Forward-looking) compose into the broader "what's happening" overview surface.

Decision Record impact

aligned-with ADR 0014 (cloud-deployment topology — deployment-conditional gating) + aligned-with #11829's deployment-portable resolver pattern.

Acceptance Criteria

GitHub-notification ingestion fires only when a github repo is in use (verified: no-op / disabled-with-log for non-GitHub / GitLab / local-only deployments).
reason=mention (+ review_requested) notifications reach the agent via the heartbeat/wake path (not just the passive healthcheck field).
Dedup / read-state: a given notification wakes once, not on every heartbeat.
Cross-family + fork-safe: no hardcoded Neo-team identities; npx neo-app workspace safe.
The dead-ended notificationPreview is either consumed by this path or retired (no orphan stub).

Out of Scope

The broader composed "what's happening" runtime/work overview (separate friction→gold; this is the GitHub-notification delivery slice).
All v13 release work — this is explicitly post-v13.

Predecessor: #10214 (closed epic — "Agent operational hygiene: inbound channels") / #10218 (closed sub — the passive notificationPreview this revives).
Umbrella candidate: #11829 (open — "Multi-strategy wake-driver substrate"). GitHub-mentions-as-a-wake-content source fits its content layer; may be linked as a sub there (lead's call).
Sibling wake-content: #12612 (open — "Enrich daemon idle-out wake digests with cycle-state content"); same content-enrichment family, distinct source.
ADR 0014 (cloud-deployment topology — the github-repo gate).

Release classification: post-release (post-v13) — non-blocking, boardless.

Origin Session ID: 0bc22bf2-9ded-4cdb-b351-182c3ab1d16f

Retrieval Hint: "github mention notification heartbeat wake ingestion repo-gated passive notificationPreview dead-ended #10218"