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.

Neo.mjs - Self-Evolving Software Organism

Frontmatter

title	feat: Scaffold Autonomous Agent State Signaling (#9951)
author	tobiu
state	Merged
createdAt	Apr 13, 2026, 7:10 PM
updatedAt	Apr 13, 2026, 7:15 PM
closedAt	Apr 13, 2026, 7:15 PM
mergedAt	Apr 13, 2026, 7:15 PM
branches	`dev` ← `agent/9951-agent-state-signaling`
url	https://github.com/neomjs/neo/pull/9979

Merged

tobiu commented on Apr 13, 2026, 7:10 PM

Overview

This pull request implements the autonomous agent state signaling mechanism (signal_state_transition endpoint) to resolve #9951.

Architectural Changes

openapi.yaml:
- Scaffolded the /system/state/transition POST endpoint to act as a deterministic state-trap for Headless Orchestration.
- Defined boundaries for Enum execution states: PR_OPENED, HANDOFF, and BLOCKED.
AgentStateService.mjs:
- Implemented the service to trap state transitions.
- If state: 'BLOCKED' is signaled alongside a target_id, the system proxy calls IssueService.manageIssueLabels to autonomously append the agent-task:blocked tag.
toolService.mjs:
- Wired up signal_state_transition to expose it generically across MCP clients.

Resolves

Resolves #9951

tobiu commented on Apr 13, 2026, 7:13 PM

Input from Antigravity (Gemini 3.1 Pro):

✦ # PR Review Summary

Status: Approved

Excellent execution on shifting autonomous state signaling into a dedicated MCP endpoint! This decouples the headless orchestrator's state lifecycle from the heavy github-workflow capabilities, providing a robust, isolated trap for reporting states (BLOCKED, HANDOFF) natively.

📊 Evaluation Metrics

[ARCH_ALIGNMENT]: 100 - The code aligns perfectly with the Neo.mjs standard class architecture extending Neo.core.Base and correctly integrates with the IssueService to automatically label blocked states.

[CONTENT_COMPLETENESS]: 100 - The OpenApi configuration is cleanly defined and AgentStateService.mjs incorporates comprehensive 'Anchor & Echo' JSDoc to maintain contextual completeness.

[EXECUTION_QUALITY]: 100 - Safely handled JSON schema inputs; manual endpoint tests and OpenAPI parsing validated successfully during continuous background MCP process checks.

[PRODUCTIVITY]: 100 - Successfully completes the objectives outlined in Epic/Issue #9951.

[IMPACT]: 80 - Critical for terminating the swarm loop locally without requiring full CLI execution logic.

[COMPLEXITY]: 40 - Straightforward routing but highly critical path execution logic.

[EFFORT_PROFILE]: Quick Win - High ROI for infrastructure stability via deterministic traps.

🕸️ Context & Graph Linking

Target Epic / Issue ID: Resolves #9951

Related Graph Nodes: Headless Orchestration, Swarm Intelligence Handoff

🧠 Graph Ingestion Notes

[KB_GAP]: N/A

[TOOLING_GAP]: N/A

[RETROSPECTIVE]: The "Trick Question" from the Commander identifies a crucial Tiered Capability Matrix requirement. We MUST NOT grant full github-workflow access uniformly to all models in the swarm. "Thin Client" Frontier models (Gemini, Opus) possess the reasoning to safely sequence complex GraphQL/CLI PR logic. Conversely, "Thick Client" local/headless engines (like Gemma) should operate within tight boundaries, utilizing deterministic endpoints like this exact signal_state_transition tool to safely relay states (BLOCKED, PR_OPENED) back to the Orchestrator without the risk of destructive API hallucinogenic loops.

📋 Required Actions

To proceed with merging, please address the following:

Merge PR #9979.

Follow-Up System Enhancement: Architect MCP Capability Gating by Model Tier (e.g. limit local execution loops exclusively to simplified state traps while preserving manageIssueLabels and createIssue exclusively for Frontier-level orchestration instances).