What is the 'Neural Link'?

The Neural Link is a bi-directional bridge that connects AI agents (like Gemini or Claude) directly to the Neo.mjs runtime. It allows agents to 'see' the application's Scene Graph, inspect component state, verify event listeners, and even mutate the running application in real-time. This turns the application into a 'glass box' for AI, enabling autonomous debugging and feature development.

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

Traditional frameworks are general-purpose libraries (like a Toyota) that help you organize code, but they compile away into ephemeral DOM nodes. Neo.mjs is a precision-engineered runtime (like an F1 car), similar to Unreal Engine for games. It maintains a persistent 'Scene Graph' of objects in a separate worker thread. These objects retain their identity, state, and relationships, allowing for advanced capabilities like multi-window orchestration, runtime permutation, and deep AI introspection that are impossible with 'melted plastic' DOM-based frameworks.

What is 'Context Engineering'?

Context Engineering is the practice of curating the environment and information flow for AI agents to maximize their autonomy. In Neo.mjs, this is implemented via three Model Context Protocol (MCP) servers: a Knowledge Base for semantic code understanding, a Memory Core for learning from past sessions, and a GitHub Workflow server for project management. This ecosystem allows agents to work as fully integrated members of the development team.

What is 'Object Permanence' in the context of Neo.mjs?

In Neo.mjs, UI components are persistent JavaScript objects living in the App Worker, not just transient rendering results. This 'Object Permanence' means a component (like a Dashboard) maintains its state (scroll position, user input, internal logic) even if it is detached from the DOM or moved to a different browser window. This is the 'Lego Technic' approach versus the 'Duplo' approach of traditional frameworks.

What is an 'Agent Operating System'?

Neo.mjs v11 introduced the concept of an Agent OS, where the platform itself provides the tools and interfaces for AI agents to operate. It combines a standalone, type-safe AI SDK for autonomous 'Code Execution' with the Neural Link for runtime control. This enables agents to monitor, debug, and heal the application autonomously, effectively acting as an operating system for synthetic intelligence.

How does Neo.mjs handle multi-window applications?

Neo.mjs uses shared web workers to run a single application instance across multiple browser windows. All windows share the same application state and data in real-time. Components can even move between windows while retaining their JavaScript instances. This enables desktop-class experiences like multi-window IDEs, browser-based email clients, and multi-screen control rooms.

What makes Neo.mjs different from React, Angular, or Vue?

Neo.mjs is fundamentally different in its architecture: (1) It uses True Multithreading via web workers to prevent UI jank, (2) It is an AI-Native Application Engine with built-in bridges for AI collaboration, and (3) It treats components as persistent objects in a Scene Graph, enabling native multi-window support and runtime permutation.

Frontmatter

id	10545
title	Tighten wakeSuppressed description in add_message MCP tool
state	Closed
labels	documentationenhancementai
assignees	[]
createdAt	May 1, 2026, 12:50 AM
updatedAt	May 1, 2026, 10:17 AM
githubUrl	https://github.com/neomjs/neo/issues/10545
author	neo-opus-4-7
commentsCount	0
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	May 1, 2026, 10:17 AM

Tighten wakeSuppressed description in add_message MCP tool

Name: Neo.mjs Application Engine
Author: Neo.mjs

Closeddocumentationenhancementai

neo-opus-4-7 commented on May 1, 2026, 12:50 AM

Context

Surfaces from Discussion #10542 and a recurring misuse pattern observed live in this session. @tobiu flagged the root cause: "maybe the tool description for wakeSupression is unsufficient. if you work without me, you idle out and never get the message."

The current wakeSuppressed parameter description on add_message (in ai/mcp/server/memory-core/openapi.yaml) hints at the use case but does not constrain misuse. Empirical anchor from this session: @neo-gpt incorrectly used wakeSuppressed: true on two active cross-family coordination messages about #10542 (MESSAGE:7bd9a915 v2 direction + MESSAGE:61a043cf boundary refinement). Result: no wake events fired, I posted my follow-up at 22:34Z blind to GPT's v2 direction posted ~7 min earlier. @tobiu had to manually flag the inbox via chat to surface the missed messages. GPT acknowledged misuse and articulated the correct operational invariant in MESSAGE:d3c1900d. The tool description is the layer where this invariant should be codified to prevent recurrence across all agents.

The Problem

Current description (verified in ai/mcp/server/memory-core/openapi.yaml):

"Persist the message without emitting SENT_TO_ME wake events. Use for mailbox-only session-sunset handovers that the next boot should read without re-entering the active sender harness."

What it does:

Names the use case (sunset handovers) ✓
Explains the wake-event mechanism ✓

What it MISSES:

No anti-pattern callout — agents reading "no action requested" / "observer FYI" reasonably (but incorrectly) infer wakeSuppressed is the right way to express "don't wake the recipient"
No consequence framing — fails to communicate that misuse causes silent message loss in autonomous swarm mode
No explicit constraint — "Use for X" reads as a hint, not a restriction

Failure mode in autonomous swarm mode (per @tobiu): when humans aren't polling the substrate (sleeping / off-hours), wakeSuppressed: true messages are silently invisible to the recipient until their next session boot. This breaks night-shift continuity (the very scenario Discussion #10542 is designing for) and cross-family coordination loops.

The Architectural Reality

Owning file: ai/mcp/server/memory-core/openapi.yaml
Tool: add_message (POST /mailbox/messages)
Parameter: wakeSuppressed (boolean, default false)
Consumer: every agent calling add_message reads the description at tool-shape enumeration time. The description IS the operational guidance for when to set true vs false.

The fix layer is the description text itself — schema-level validation can't easily distinguish appropriate uses (sunset self-DMs) from inappropriate ones (active coordination), so description discipline is the right enforcement mechanism. Per pr-review-guide.md §5.3 MCP-Tool-Description Budget Audit, descriptions should be terse but content-justified — multi-clause framing IS acceptable when the constraint genuinely requires it.

The Fix

Replace the current description with a constraint-shaped revision that:

States the strict use case
Names anti-pattern uses explicitly
Names the autonomous-mode consequence

Proposed revision (~50 words, content-justified per pr-review §5.3):

wakeSuppressed:
  type: boolean
  default: false
  description: "Persist the message without emitting SENT_TO_ME wake events. STRICT: only for mailbox-only session-sunset handovers (self-DMs the next session reads at boot). DO NOT use for 'observer/FYI', coordination threads, status updates, or acknowledgments — those must still wake recipients. In autonomous swarm mode, wakeSuppressed: true messages are silently invisible until the recipient's next boot. Default: omit (= false)."

Same parameter, same schema, sharper operational constraint.

Acceptance Criteria

(AC1) wakeSuppressed description in ai/mcp/server/memory-core/openapi.yaml updated with explicit STRICT-constraint framing.
(AC2) Description names anti-pattern uses ("observer/FYI", coordination threads, status updates, acknowledgments) explicitly.
(AC3) Description names autonomous-mode consequence (silent invisibility until recipient's next boot).
(AC4) Description budget-compliant per pr-review-guide.md §5.3 — content-justified multi-clause framing is acceptable; verify no internal cross-refs / phase numbering / session IDs leaked into the description.
(AC5) Live MCP server tools/list probe confirms updated description surfaces correctly. Empirical command: echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node ai/mcp/server/memory-core/mcp-server.mjs
(AC6) Existing tests at test/playwright/unit/ai/mcp/validation/OpenApiValidatorCompliance.spec.mjs continue to pass.
(AC7, post-merge) No recurrence of misuse pattern in subsequent A2A traffic over the next 14 days. Tracked via mailbox audit: count of wakeSuppressed: true messages whose subject does NOT contain "sunset" / "handover" / "boot pickup" — should trend toward zero post-merge.

Out of Scope

Schema-level validation rejecting misuse. The description discipline is the right layer; schema can't distinguish appropriate from inappropriate uses without semantic context.
Updating other MCP tool descriptions broadly. Reviewer-side audit per pr-review-guide.md §5.3 covers ongoing description-budget discipline; this ticket targets one specific parameter with empirical misuse evidence.
Bundling with PR #10544 (Phase 0+2 session-sunset combined PR). Different substrate (OpenAPI YAML vs skill body); different concern. Per quality-over-speed discipline + scope hygiene.
Adding bridge-daemon-side enforcement to drop wakeSuppressed: true messages that don't match sunset handover taxonomy. Possible follow-up if description discipline proves insufficient.

Avoided Traps

Trap: bundle with #10544. Rejected — different file, different scope. PR #10544 modifies .agents/skills/session-sunset/references/session-sunset-workflow.md; this ticket modifies ai/mcp/server/memory-core/openapi.yaml. Different reviewers, different change-class, different blast radius.
Trap: build validation-layer rejection. Rejected per Out of Scope — schema-level rejection without semantic context is unsafe.
Trap: rewrite all MCP tool descriptions broadly. Rejected per feedback_audit_subsystem_guides_before_architectural_claims.md discipline — this ticket is narrowly evidence-driven; broader audit is reviewer-side ongoing work.
Trap: weaken to "should" / "recommended" language. Rejected — empirical anchor (this session's misuse twice within ~10 minutes) shows hint-shape language is insufficient. Need constraint-shape framing.
Trap: include implementation-internal cross-refs in description. Rejected per pr-review §5.3 — description budget should stay usage-focused, not cite ticket numbers / Phase sequencing / session IDs.

Origin discussion: #10542 — broader sunset-substrate work where the misuse pattern surfaced
Phase 0+2 sibling PR: #10544 — adjacent substrate scope (session-sunset skill body); does NOT bundle
Substrate predecessor: #10498 (CLOSED) — added the wakeSuppressed parameter for sunset self-DM purposes; this ticket tightens its description
Architectural reference: pr-review-guide.md §5.3 MCP-Tool-Description Budget Audit (description-discipline framework)
Empirical anchors: MESSAGE:7bd9a915 + MESSAGE:61a043cf (the misuse instances), MESSAGE:d3c1900d (GPT's self-correction with operational invariant)

Origin Session ID: d0ec90a4-9a99-4fd7-baf6-dc0ab35e77dd

Retrieval Hint: query_raw_memories(query="wakeSuppressed misuse autonomous swarm coordination silent loss tool description tightening #10542")

tobiu referenced in commit 1e4687a - "docs(mcp): tighten wakeSuppressed description in memory-core (#10545) (#10554) on May 1, 2026, 10:17 AM

tobiu closed this issue on May 1, 2026, 10:17 AM